Webhooks

webhook チャネルは、汎用的なインバウンド/アウトバウンド HTTP アダプターです。指定したポートで独自の組み込み HTTP サーバーを実行し、JSON 形式のメッセージを受け取ってエージェントに渡し、（オプションで）エージェントの応答を指定した URL に POST します。HTTP POST を生成できる任意のシステム向けの汎用アダプターとして使用できます。

ゲートウェイの /webhook エンドポイントとは別物です。 ゲートウェイサービスには、HTTP経由でエージェントにアクセスするペアリング済みクライアント向けの独自の POST /webhook があり、これは [gateway] の下に存在し、運用 → ネットワークデプロイで説明されています。このページでは [channels.webhook] チャネルのみを説明します。

インバウンド

チャネルは 0.0.0.0:{port} にバインドし、POST {listen_path} をルーティングします。

リクエストボディ（JSON）:

{
  sender: alice,
  "内容": こんにちは、エージェント。,
  thread_id: optional-conversation-id
}

sender: 必須。メッセージの送信者IDとして使用されます。
content: 必須。エージェントに渡されるユーザーメッセージです。内容が空の場合は 400 を返します。
thread_id: 省略可能。設定した場合、エージェントの返信は同じスレッドを対象とします。設定しない場合、返信は sender を対象とします。

成功すると 200 OK が返されます。不正な形式の JSON または空の content の場合は 400 が返されます。バックプレッシャー（チャネルキューが満杯）の場合は 503 が返されます。

署名の検証

secretを設定した場合、すべての受信リクエストにX-Webhook-Signatureヘッダーを含める必要があります：

X-Webhook-Signature: sha256=<hex-encoded HMAC-SHA256 of the raw body>

チャネルは HMAC-SHA256(secret, raw_body) を計算して16進数にエンコードし、ヘッダー値と比較します（デコード前に sha256= プレフィックスが除去されます）。不一致またはヘッダーが欠落している場合は 401 を返します。

secret が未設定の場合、チャネルは起動を拒否します（リスナーは起動時にエラーで中断し、シークレットを設定するようオペレーターに指示します）。有効化された Webhook チャネルは、常に設定済みの secret を必要とします。これは意図的なフェイルファストです。エージェントアクセスを持つ認証されていない Webhook リスナーは、いかなるデプロイにも存在すべきでないオープンな入口だからです。

破壊的変更。 これまでリバースプロキシの背後でシークレットなしにリスナーを実行していた、またはプライベートネットワークにバインドしていたデプロイでは、今後 [channels.webhook.<alias>].secret に secret を設定する必要があります。シークレットなしのフォールバック経路は削除されました。有効化された webhook リスナーは、いかなるデプロイトポロジーにおいても晒されるべきではない無条件のリスクとして扱われます。この状況にある運用者は secret を設定し、リスナーを既存のリバースプロキシの背後に置いたままにするか、引き続きプライベートネットワークにバインドしてください。どちらでも問題ありません。今や重要な役割を担うのはシークレットです。

アウトバウンド

send_url を設定すると、すべてのエージェントの応答が、その URL への HTTP リクエストとして配信されます。

{send_method} {send_url}
Authorization: {auth_header}    # auth_header が設定されている場合のみ
Content-Type: application/json

{
  "content": "agent reply text",
  "thread_id": "optional thread id",
  "recipient": "optional recipient id"
}

send_method は POST（デフォルト）または PUT です。それ以外の値は POST にフォールバックします。
auth_header は Authorization ヘッダーの値としてそのまま送信されるため、スキーム自体を含めてください（例: Bearer xyz、Basic dXNlcjpwYXNz）。
recipient は空の場合は省略されます。
非 2xx レスポンスはログにエラーを発生させます。エージェントの応答は失敗とみなされます。

send_url が設定されていない場合、エージェントの応答は警告なく破棄されます（debug レベルでログに記録されます）。これは、応答が別のチャネルを通じて配信される、ファイア・アンド・フォーゲット型のインバウンドフローに適した設定です。

公開

チャネルは 0.0.0.0 に直接バインドされます。これをパブリックインターネット上に公開するには:

リバースプロキシ: nginx / Caddy / Traefik で TLS を終端し、チャネルのポートにプロキシします。運用 → ネットワークデプロイメントを参照してください。
トンネル: [tunnel]（ngrok、cloudflare、または tailscale）を設定すると、デーモンがチャネルとともにトンネルを起動します。
ローカル限定: プライベートネットワーク内で実行し、プロデューサーから LAN/ループバックアドレスに直接アクセスさせます。

公開する場合は必ず secret と併用してください。認証なしの Webhook リスナーは、エージェントへの無防備な入口になります。

アウトバウンドの再試行

send_url が設定されている場合、送信側の配信は一時的な失敗、ネットワークエラー、HTTP 429、HTTP 5xx を再試行し、指数バックオフ（±25% のジッター）を用い、retry_max_delay_ms を上限とします。429 以外の 4xx 応答は再試行せず即座に失敗します。サーバーが 429 または 503 で Retry-After ヘッダーを返した場合、その値が尊重され、同じく retry_max_delay_ms で制限されます。max_retries = 0 を設定すると、送りっぱなし（fire-and-forget）になります。

Keyboard shortcuts

ZeroClaw Docs