アプリの Webhook

アプリの Webhook は、CI ランナーや監視ツール、外部サービスが POST するだけで GameVox のチャンネルにメッセージを投稿できる、チャンネルごとの URL です。ゲートウェイセッションは不要です。メッセージはボットのアバターとユーザー名で、ボットユーザーとして投稿されます。

上限

1 アプリケーションにつき Webhook 50 個。
名前: 1〜80 文字。
本文: 1 メッセージあたり 1〜4000 文字。
Webhook 1 つにつきチャンネル 1 つです。Webhook の作成には、そのチャンネルがあるサーバーで manage_server 権限が必要です。

トークンの形式

WH.{8 文字の接頭辞}.{base64 のランダム文字列}

例: WH.aB7xZ2k1.q9F7v1NkN3J2Wm8L6PpV5cU0Yr1zQbXa

完全なトークンは作成時にちょうど 1 回だけ表示されます。保存されるのは bcrypt ハッシュと、表示用の接頭辞・末尾 4 文字だけです。トークンを紛失した場合は、その Webhook を削除して作り直してください。

Webhook を作成する（ポータル）

アプリケーションを開き → Webhook タブ → 新規 Webhook。管理できるサーバーを選び、チャンネルを選び、名前を付けます。表示ダイアログに完全なトークンと、そのまま貼り付けられる実行 URL が出ます。閉じる前にコピーしてください。ポータルで再表示されることはありません。

エンドポイント

認証方法は 2 つです。管理用のボットトークンと、実行用の 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）。1 メッセージに複数の埋め込みを含められます。
添付ファイル: payload_json パートを含む multipart/form-data でアップロードします。レスポンスには CDN の URL が含まれます。
返信先の指定: payload_json に message_reference を渡します。
?wait=true: 常に有効です。レスポンスは必ず確定したメッセージになります。
編集 / 削除: /webhooks/{id}/{token}/messages/{message.id} への PATCH / DELETE は Discord と同じです。
ユーザー名 / アバターの上書き: 未対応です。メッセージは常にアプリケーションのボットユーザーとして投稿されます。

エラー

401: トークンがない、形式が不正、または一致しません。
404: Webhook が削除済み、または id が存在しません。
400: content が空で埋め込みも添付もない、または content が 4000 文字を超えています。
405: このルートでは対応していないメソッドです。
413: 添付ファイルが 1 ファイルあたりのサイズ上限を超えています。

ローテーション

v1 にはその場でローテーションするエンドポイントはありません。Webhook を削除して新しく作成してください。削除した時点で古いトークンは直ちに使えなくなります（実行経路は論理削除された行を除外します）。

Discord との違い

Webhook はアプリケーションが所有し、サーバー管理者のものではありません。チャンネルを削除しても Webhook のレコードは削除されず、次の実行では参照時のチャンネル結合で 404 になります。
リクエストごとの username / avatar_url の上書きはできません。アイデンティティはボットユーザーに固定されます。
チャンネルごとの上限はなく、上限はアプリケーション単位（50 個）です。
認証は bcrypt で検証するため、トークンの比較は意図的に遅くなっています。短い間隔で連続的にエンドポイントを叩かないでください。
セルフホストサーバー: Webhook はセルフホストのサーバーには転送されません。セルフホストのギルドを対象にした Webhook のエンドポイントはすべて 404 を返します。セルフホストのドキュメントをご覧ください。

← ドキュメントに戻る