Webhooks

Webhook とは、TicketWave があなたに送信する HTTP リクエストです。サーバーで何かが起こるたびに — チケットが開かれたり、メンバーがブラックリストに追加されたりすると — TicketWave はあなたが管理する URL に JSON 本文を POST します。

これが Log Channels との違いです。ログチャンネルは人が読むために Discord に embed を書き込みますが、webhook は生のイベントをあなたのコードに渡します。

エンドポイントを作成する

エンドポイントの要件

リクエスト

すべての配信は JSON 本文を持つ POST です。

Headers

Body

すべてのペイロードは同じエンベロープを使います。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 オブジェクトについては Event Reference を参照してください。

署名の検証

あなたのエンドポイント URL を見つけた人は、そこに POST リクエストを送れます。署名は、それが本物の TicketWave 配信なのか、偽造されたものなのかを見分けるためのものです。

署名の作り方

TicketWave はタイムスタンプと 生の リクエスト本文をドットで連結し、その結果に対して HMAC-SHA256 をあなたのエンドポイントシークレットで実行します。

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

ヘッダーには、そのダイジェストが hex エンコードされ、プレフィックス付きで入ります: sha256=<digest>。

受信側で行うこと

完全な実装は Example Server のページにあります。

リトライ

失敗した配信は自動的に再試行されます。

配信は 順序保証されません。2 つのチケットが同時に作成された場合、リクエストはどちらの順番でも届く可能性があります。順序が重要なら、本文の timestamp フィールドを使ってください。

配信履歴

ダッシュボードの Webhooks ページには、すべての配信がステータス、レスポンスコード、所要時間、試行回数とともに一覧表示されます。行を開くと、送信された正確なリクエストペイロードと、サーバーが返したレスポンスを確認できます。

失敗した配信は、詳細ページから Retry Webhook で再送できます。元のペイロードを同じエンドポイントにもう一度送信し、新しい配信として記録します。

トラブルシューティング

次のステップ

• Event Reference（すべてのイベントとそのペイロード）
• Example Server（実行可能な Express 受信側）
• Log Channels（同じイベントを Discord に投稿するもの）