Webhook Plugin

Webhooks Plugin は、認証済みの HTTP ルートを追加し、信頼された外部システム （Zapier、n8n、CI ジョブ、内部サービス）がカスタム Plugin を作成することなく、 HTTP 経由で管理対象の OpenClaw TaskFlow を作成および操作できるようにします。

この Plugin は Gateway プロセス内で実行されます。リモート Gateway の場合は、 そのホストにインストールして設定し、Gateway を再起動してください。初期状態では ルートが設定されていないため、少なくとも 1 つのルートを追加するまでは何も動作しません。

ルートを設定する

plugins.entries.webhooks.config 配下に設定します。

{  plugins: {    entries: {      webhooks: {        enabled: true,        config: {          routes: {            zapier: {              path: "/plugins/webhooks/zapier",              sessionKey: "agent:main:main",              secret: {                source: "env",                provider: "default",                id: "OPENCLAW_WEBHOOK_SECRET",              },              controllerId: "webhooks/zapier",              description: "Zapier TaskFlow bridge",            },          },        },      },    },  },}

ルートのフィールド：

secret には、プレーン文字列または SecretRef を指定できます：{ source: "env" | "file" | "exec", provider: "default", id: "..." }。

設定された各ルートは、シークレットを現在解決できるかどうかに関係なく、起動時に登録されます。 解決できないシークレットによってルートが無効化またはスキップされることはありません。 シークレットを解決できるようになるまで、そのルートへのリクエストは認証に失敗します（401）。 SecretRef の値はリクエストごとに再解決されるため、基になるシークレット （環境変数、ファイル、または exec の出力）をローテーションすると、 Gateway を再起動せずに反映されます。

セキュリティモデル

各ルートは、設定された sessionKey の TaskFlow 権限で動作します。つまり、 そのセッションが所有する任意の TaskFlow を確認および変更できます。TaskFlow へのアクセスは 常に api.runtime.tasks.managedFlows.bindSession(...) を経由するため、ルートが バインドされたセッションの外部で動作することはありません。影響範囲を限定するには：

• ルートごとに強力で一意なシークレットを使用します。
• インラインの平文シークレットより SecretRef を優先します。
• ワークフローに適合する最小範囲のセッションにルートをバインドします。
• 必要な特定の Webhook パスのみを公開します。

各パスのリクエスト処理順序は次のとおりです。HTTP メソッド（POST のみ）と Content-Type: application/json の確認、固定ウィンドウ方式のレート制限 （パスとクライアント IP のキーごとに 60 秒間で 120 リクエスト、追跡するキーは最大 4,096 個）、 処理中リクエスト数の制限（キーごとに同時 8 リクエスト、追跡するキーは最大 4,096 個）、 共有シークレット認証、最後に 256 KB／15 秒を上限とする JSON 本文の読み取りです。 前段の確認に失敗したリクエストは、後続の処理には到達しません。

リクエスト形式

Content-Type: application/json と、 Authorization: Bearer <secret> または x-openclaw-webhook-secret: <secret> の いずれかを指定して POST リクエストを送信します。

curl -X POST https://gateway.example.com/plugins/webhooks/zapier \  -H 'Content-Type: application/json' \  -H 'Authorization: Bearer YOUR_SHARED_SECRET' \  -d '{"action":"create_flow","goal":"Review inbound queue"}'

サポートされるアクション

変更アクション（set_waiting、resume_flow、finish_flow、fail_flow、 request_cancel）では、楽観的同時実行制御のために flowId と expectedRevision が 必要です。古いリビジョンを指定すると 409 revision_conflict が返されます。

create_flow

{  "action": "create_flow",  "goal": "Review inbound queue",  "status": "queued",  "notifyPolicy": "done_only"}

run_task

許可される runtime の値は subagent、acp です。startedAt、lastEventAt、 progressSummary は、status が "running" の場合にのみ有効です。それ以外の ステータスで送信すると 400 invalid_request が返されます。

{  "action": "run_task",  "flowId": "flow_123",  "runtime": "acp",  "childSessionKey": "agent:main:acp:worker",  "task": "Inspect the next message batch"}

レスポンス形式

{  "ok": true,  "routeId": "zapier",  "result": {}}

{  "ok": false,  "routeId": "zapier",  "code": "not_found",  "error": "TaskFlow not found.",  "result": {}}

フローおよびタスクのビューには所有者／セッションのメタデータが含まれないため、 レスポンスからルートにバインドされた sessionKey が漏れることはありません。 code の値には、not_found、not_managed、revision_conflict、 persist_failed、cancel_requested、cancel_pending、terminal、 invalid_request、request_rejected が含まれます。また、上記の名前付きコードで 扱われない理由により変更が拒否された場合は、アクション固有のフォールバックコード （mutation_rejected、create_rejected、task_not_created、cancel_rejected） が使用されます。

関連項目

• フック - 内部のイベント駆動型フックと、この HTTP ベースの TaskFlow ブリッジとの違い
• Gateway Webhook（hooks.* 設定） - 独立した汎用 Gateway HTTP エンドポイント機能。この Plugin のルートとは異なります
• Plugin ランタイム SDK
• CLI Webhook