웹훅

웹훅은 TicketWave가 당신에게 보내는 HTTP 요청입니다. 서버에서 무언가가 발생할 때마다 — 티켓이 열리거나, 멤버가 블랙리스트에 추가되거나 — TicketWave가 당신이 소유한 URL로 JSON 본문을 POST합니다.

이것이 로그 채널과의 차이입니다. 로그 채널은 사람이 읽을 수 있도록 Discord에 임베드를 작성하고, 웹훅은 원시 이벤트를 당신의 코드에 전달합니다.

엔드포인트 만들기

엔드포인트 요구 사항

요청

모든 전달은 JSON 본문을 가진 POST입니다.

헤더

본문

모든 페이로드는 같은 봉투 형식을 사용합니다. 이벤트 유형마다 data만 다릅니다:

{
  "event": "ticket.created",
  "timestamp": "2026-08-26T08:23:11.000Z",
  "guild_id": "123456789012345678",
  "data": {
    "ticket_id": "ticket-1042",
    "ticket_num_id": 1042,
    "channel_id": "998877665544332211",
    "category": "🤖 Support",
    "user": { "id": "987654321098765432", "username": "Luna" },
    "created_at": "2026-08-26T08:23:11.000Z"
  }
}

모든 유형의 data 객체는 이벤트 레퍼런스를 참고하세요.

서명 검증하기

당신의 엔드포인트 URL을 알아낸 사람은 누구나 POST 요청을 보낼 수 있습니다. 서명은 실제 TicketWave 전달과 위조된 요청을 구분하는 방법입니다.

서명이 만들어지는 방식

TicketWave는 타임스탬프와 원시 요청 본문을 점으로 이어 붙인 뒤, 엔드포인트 비밀키를 사용해 그 결과에 HMAC-SHA256을 적용합니다:

signed_payload = X-TicketWave-Timestamp + "." + raw_request_body
signature      = HMAC_SHA256(signed_payload, your_endpoint_secret)

헤더에는 그 다이제스트가 16진수로 인코딩되어 접두사와 함께 들어갑니다: sha256=<digest>.

수신기가 해야 할 일

완전한 구현 예시는 Example Server 페이지에 있습니다.

재시도

실패한 전달은 자동으로 재시도됩니다.

전달은 순서가 보장되지 않습니다. 두 티켓이 동시에 생성되면 요청이 어느 순서로든 도착할 수 있습니다 — 순서가 중요하다면 본문의 timestamp 필드를 사용하세요.

전달 기록

대시보드의 Webhooks 페이지에는 모든 전달의 상태, 응답 코드, 소요 시간, 시도 횟수가 표시됩니다. 행을 열면 전송된 정확한 요청 페이로드와 서버가 반환한 응답을 볼 수 있습니다.

실패한 전달은 상세 페이지에서 Retry Webhook으로 다시 보낼 수 있습니다. 같은 엔드포인트로 원래 페이로드를 다시 보내며, 새 전달 기록이 생성됩니다.

문제 해결

다음 단계

• Event Reference (모든 이벤트와 페이로드)
• Example Server (실행 가능한 Express 수신기)
• Log Channels (같은 이벤트를 Discord에 게시)