#Webhook

ウェブフックは、秘密のURLを介して、1つのチャネルにメッセージを投稿します。ボットコード、ゲートウェイループ、Authorizationヘッダーは必要ありません。HTTPリクエストを作成できる場合は、Disbandに投稿できます。

Webhooksはボットとは別です。CI、監視、ゲームサーバー、フォーム、またはURLを呼び出すことができるその他のものからの一方通行の通知にはウェブフックを使用します。イベントを読み取るかメッセージに反応する必要がある場合はボットを使用します。

#ウェブフックを作成する

スペースには管理Webhooksの権限が必要です。

1. スペース設定→統合→Webhooksを開きます。
2. チャネルを選択し、「新しいウェブフック」を選択します。
3. 名前をつけて、気に入ったらアバターも付けてください。
4. Webhook URLをコピーします。

URLは次のようになります。

https://disband.dev/webhook/12345678/01234567890123456789012345

同じエンドポイントはhttps://disband.dev/api/webhooks/<space key>/<token>でも提供されています。

その画面から、ウェブフックの名前を変更したり、トークンをリセットしたり、削除したりできます。トークンをリセットすると、古いURLはすぐに無効になります。ウェブフックを削除すると、投稿が停止しますが、チャンネルにすでに送信したメッセージが残ります。

#ウェブフックを実行する

POSTをURLのウェブフックに送信し、JSONのボディを添付します。

curl -X POST 'https://disband.dev/webhook/12345678/01234567890123456789012345' \
  -H 'Content-Type: application/json' \
  -d '{
    "content": "Deploy finished — **v2.4.1** is live.",
    "username": "Deploy bot",
    "avatar_url": "https://example.com/deploy.png"
  }'

成功したリクエストは204 No Contentを返します。代わりに?wait=trueを追加して、作成されたメッセージオブジェクトを受信してください。

curl -X POST 'https://disband.dev/webhook/12345678/01234567890123456789012345?wait=true' \
  -H 'Content-Type: application/json' \
  -d '{ "content": "Hello from the other side." }'

#ボディフィールド

usernameには、disbandまたはclydeが含まれてはいけません。これは、プラットフォームスタッフを装ったウェブフックを防止します。

ファイル添付物はまだサポートされていません。マルチパートリクエストは解析できますが、ファイルは保存されません。ファイルをアップロードする必要がある場合は、ボットを使用してください。

#制御を言及する

デフォルトでは、ウェブフックはユーザーの言及と@everyone / @here（Discordと同じ）の両方を解析します。

誰もにpingしないために：

{ "content": "Build 184 finished.", "allowed_mentions": { "parse": [] } }

ユーザーの言及を許可しますが、すべての人を許可しない場合：

{
  "content": "Thanks @polar.",
  "allowed_mentions": { "parse": ["users"] }
}

データベースは、抑制されているときにまだ@everyoneを保存しますが、通知は送信されません。フィールドが完全に欠落している場合、すべてが解析されます。

#メッセージオブジェクト

?wait=trueを使用すると、応答はDiscordの形をしたメッセージになります。Disbandはidでその数値メッセージIDを使用します。

{
  "id": "4821",
  "type": 0,
  "content": "Deploy finished.",
  "channel_id": "…",
  "guild_id": "…",
  "author": {
    "id": "…",
    "username": "Deploy bot",
    "avatar": "https://example.com/deploy.png",
    "discriminator": "0000",
    "bot": true
  },
  "attachments": [],
  "embeds": [],
  "mentions": [],
  "mention_roles": [],
  "mention_everyone": false,
  "pinned": false,
  "tts": false,
  "timestamp": "2026-10-19T20:15:00.000Z",
  "edited_timestamp": null,
  "flags": 0,
  "components": [],
  "webhook_id": "…"
}

#メッセージを管理する

ウェブフックは、投稿したメッセージを取得、編集、削除できます。実行応答から数値メッセージIDを使用してください。

例の編集：

curl -X PATCH 'https://disband.dev/webhook/12345678/01234567890123456789012345/messages/4821' \
  -H 'Content-Type: application/json' \
  -d '{ "content": "Deploy finished — rolled back." }'

そのウェブハックによって作成されたメッセージのみを変更できます。別のウェブハックは404 Unknown Messageを受け取ります。

#ウェブフック自体を管理する

URL を通じて削除すると、統合画面で削除するのと同じ方法で永久的に削除されます。

#レート制限

各ウェブフックは2秒間に5件のリクエストまで制限されています。制限はトークンによって決まりますので、騒々しいウェブフックが他のウェブフックを遅らせたりすることはありません。

制限付きのリクエストは429を返します。

{
  "message": "You are being rate limited.",
  "retry_after": 1.34,
  "global": false
}

応答にはRetry-After（整数秒）と通常のX-RateLimit-*ヘッダーも含まれています。遅延を待ち、その後再試行してください。

#エラー

エラーはDiscordの形状を使用します。

{ "message": "Unknown Webhook", "code": 10015 }

404 Unknown Webhookは、スペースキーかトークンが間違っているかどうかをわざと言いません。

#セキュリティ

• URLを持っている人は誰でも投稿できます。公開リポジトリにコミットしたり、置いたりしないでください。 クライアント側のコードに含まれています。
• URLをAPIキーに使用するのと同じ秘密ストアに保存します。
• トークンが漏れる場合はすぐにリセットしてください。古いURLはすぐに機能しなくなります。
• Webhookは、構成されたチャネルにのみ書き込みます。メッセージを読み込むことはできません。 メンバーをリストアップするか、スペース設定を変更します。

#関連した

• 埋め込み — 埋め込みオブジェクトとその制限。
• ボット — 双方向の統合とイベント配信。
• APIリファレンス — ボット HTTP API、を含む 埋め込みサポート。