앱 웹훅

앱 웹훅은 CI 러너, 모니터링 도구, 외부 서비스가 POST만 하면 GameVox 채널에 메시지를 남길 수 있는 채널별 URL입니다. 게이트웨이 세션은 필요 없습니다. 메시지는 봇의 아바타와 사용자 이름으로, 봇 사용자로서 게시됩니다.

제한

애플리케이션당 웹훅 50개.
이름: 1~80자.
본문: 메시지당 1~4000자.
웹훅 하나에 채널 하나입니다. 웹훅을 만들려면 해당 채널이 있는 서버에서 manage_server 권한이 필요합니다.

토큰 형식

WH.{8자 접두사}.{base64 난수}

예시: WH.aB7xZ2k1.q9F7v1NkN3J2Wm8L6PpV5cU0Yr1zQbXa

전체 토큰은 생성 시 정확히 한 번만 표시됩니다. 저장되는 것은 bcrypt 해시와 표시용 접두사·마지막 4자뿐입니다. 토큰을 잃어버렸다면 그 웹훅을 삭제하고 새로 만드세요.

웹훅 만들기(포털)

애플리케이션을 열고 → 웹훅 탭 → 새 웹훅. 관리할 수 있는 서버를 고르고, 채널을 고르고, 이름을 지정하세요. 표시 창에 전체 토큰과 바로 붙여넣을 수 있는 실행 URL이 나옵니다. 닫기 전에 복사하세요. 포털에서 다시 보여 주지 않습니다.

엔드포인트

인증 방식은 두 가지입니다. 관리용 봇 토큰과 실행용 URL 토큰입니다.

봇 토큰 인증(관리)

GET    /channels/{channel.id}/webhooks
POST   /channels/{channel.id}/webhooks
GET    /guilds/{guild.id}/webhooks
GET    /webhooks/{webhook.id}
PATCH  /webhooks/{webhook.id}
DELETE /webhooks/{webhook.id}

URL 토큰 인증(실행 + 편집)

POST   /webhooks/{webhook.id}/{token}
GET    /webhooks/{webhook.id}/{token}
PATCH  /webhooks/{webhook.id}/{token}
DELETE /webhooks/{webhook.id}/{token}
PATCH  /webhooks/{webhook.id}/{token}/messages/{message.id}
DELETE /webhooks/{webhook.id}/{token}/messages/{message.id}

URL 토큰 경로에는 Authorization 헤더가 없습니다. URL 경로에 들어 있는 토큰 자체가 인증입니다. URL을 시크릿처럼 다루세요.

실행 요청

JSON 본문:

POST https://api.gamevox.com/webhooks/{webhook.id}/{token}
Content-Type: application/json

{
  "content": "빌드 #4811이 프로덕션에서 통과했습니다.",
  "embeds": [
    {
      "title": "CI 통과",
      "url": "https://ci.example.com/builds/4811",
      "description": "테스트 42개, 실패 0개.",
      "color": 3066993
    }
  ]
}

multipart/form-data 본문(첨부 파일용):

Content-Type: multipart/form-data; boundary=xyz

--xyz
Content-Disposition: form-data; name="payload_json"

{ "content": "스크린샷 참고", "embeds": [ ... ] }
--xyz
Content-Disposition: form-data; name="files[0]"; filename="crash.png"
Content-Type: image/png

...binary...
--xyz--

응답(두 콘텐츠 유형 모두 동일):

{
  "id": "1199283740192847400",
  "channel_id": "1199283740192847000",
  "content": "빌드 #4811이 프로덕션에서 통과했습니다.",
  "embeds": [ ... ],
  "attachments": [ ... ],
  "timestamp": "2026-05-21T15:42:09Z"
}

지원하는 기능

본문: 일반 텍스트, 1~4000자.
임베드: Discord 임베드 형태 전체 지원(title, description, url, color, timestamp, footer, image, thumbnail, author, fields). 메시지 하나에 여러 임베드를 넣을 수 있습니다.
첨부 파일: payload_json 파트가 있는 multipart/form-data로 업로드하며, 응답에 CDN URL이 포함됩니다.
답장 대상 지정: payload_json에 message_reference를 전달하세요.
?wait=true: 항상 적용됩니다. 응답은 언제나 확정된 메시지입니다.
편집 / 삭제: /webhooks/{id}/{token}/messages/{message.id}에 대한 PATCH / DELETE가 Discord와 같습니다.
사용자 이름 / 아바타 재정의: 지원하지 않습니다. 메시지는 항상 애플리케이션의 봇 사용자로 게시됩니다.

오류

401: 토큰이 없거나 형식이 잘못되었거나 일치하지 않습니다.
404: 웹훅이 삭제되었거나 id가 존재하지 않습니다.
400: content가 비어 있고 임베드와 첨부도 없거나, content가 4000자를 넘습니다.
405: 이 경로에서 지원하지 않는 메서드입니다.
413: 첨부 파일이 파일당 크기 제한을 넘었습니다.

교체

v1에는 제자리에서 교체하는 엔드포인트가 없습니다. 웹훅을 삭제하고 새로 만드세요. 삭제하는 즉시 이전 토큰은 동작하지 않습니다(실행 경로는 논리 삭제된 행을 제외합니다).

Discord와의 차이

웹훅은 서버 관리자가 아니라 애플리케이션이 소유합니다. 채널을 삭제해도 웹훅 레코드는 지워지지 않으며, 다음 실행에서 조회 시 채널 조인 때문에 404가 납니다.
요청마다 username / avatar_url을 재정의할 수 없습니다. 정체성은 봇 사용자로 고정됩니다.
채널별 상한은 적용하지 않으며, 상한은 애플리케이션 단위(50개)입니다.
인증을 bcrypt로 검증하므로 토큰 비교가 의도적으로 느립니다. 짧은 간격으로 엔드포인트를 반복 호출하지 마세요.
자체 호스팅 서버: 웹훅은 자체 호스팅 서버로 전달되지 않습니다. 자체 호스팅 길드를 대상으로 한 모든 웹훅 엔드포인트는 404를 반환합니다. 자체 호스팅 문서를 참고하세요.

← 문서로 돌아가기