Webhook を使う場面
ビルドの通知、外部サービスのイベント、更新の連絡には Webhook が向いています。事前に選んだテキストチャンネルへ投稿します。メッセージの読み取り、コマンドやボタンの処理、イベントへの反応にはボットを使ってください。
Webhook を作成する
テキストチャンネルの設定 → Webhook · 自動メッセージ を開きます。Webhook の作成と削除には MANAGE_CHANNELS が必要です。返されたパスとトークンを保存してください。シークレットは一度だけ表示され、データベースにはハッシュのみが保存されます。
| アカウントトークン | 操作 |
|---|---|
| GET /api/channels/:channelId/webhooks | Webhook の一覧。 |
| POST /api/channels/:channelId/webhooks | {name, author_name?, avatar_url?} → 201 {webhook, token, path}。 |
| DELETE /api/channels/:channelId/webhooks/:id | Webhook を削除。 |
アドレスと識別子はチャンネルがあるホストの API に属します。Webhook はダイレクトメッセージ、グループ、公開スペースには対応していません。
送信
POST /api/webhooks/:id/execute
Authorization: Bearer <WEBHOOK_TOKEN>
Content-Type: application/json
{ "embeds": [{
"title": "ビルド完了",
"description": "レビューできる状態になりました。",
"color": 5793266,
"fields": [{ "name": "状態", "value": "準備完了", "inline": true }]
}] }{"content":"テキスト"} も使用でき、2000 文字までです。埋め込みは最大 10 個で合計 6000 文字まで。テキストと埋め込みを併用する場合、テキストが埋め込み 1 個分の枠を使います。成功した 201 応答にはメッセージ id と channel_id が含まれます。チャンネルはリクエスト本文ではなく設定で決まります。
制限とセキュリティ
- Webhook ごとに 2 秒あたり 1 件のリクエストを受け付けます。429 のときは Retry-After: 2 に従ってください。
- 投稿者名とアバターは Webhook の作成時に固定され、任意の送信者が指定することはできません。メッセージは Webhook として表示されます。
- 送信時に作成者の権限を確認します。権限を失うと 403 になることがあります。
- 結果が不明なリクエストは、確認せずに再送しないでください。冪等性は実装されていません。
- シークレットは URL ではなく Authorization で送ってください。漏えいした場合は Webhook を削除して作り直します。
- 通知や外部画像の URL に個人データを含めるのは避けてください。