Webhooks プラグイン

The Webhooks Plugin は、信頼済みの外部システム（Zapier、n8n、CI ジョブ、内部サービス）がカスタム Plugin を書かずに、HTTP 経由でマネージド OpenClaw TaskFlows を作成して操作できるようにする認証付き HTTP ルートを追加します。

この 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: "..." }。

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

セキュリティモデル

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

• ルートごとに強力で一意の secret を使用します。
• インラインの平文 secret よりも SecretRef を優先します。
• ワークフローに合う最も狭いセッションにルートをバインドします。
• 必要な特定の Webhook パスだけを公開します。

各パスのリクエスト処理順序: HTTP メソッド（POST のみ）と Content-Type: application/json のチェック、次に固定ウィンドウのレート制限（path+client-IP キーごとに 60 秒ウィンドウあたり 120 リクエスト、追跡キーは最大 4,096）、次に処理中リクエスト制限（キーごとに同時 8 リクエスト、追跡キーは最大 4,096）、次に共有 secret 認証、次に 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" の場合にのみ有効です。他の status と一緒に送信すると 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": {}}

Flow ビューとタスクビューに owner/session メタデータが含まれることはないため、レスポンスからルートにバインドされた 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）が含まれます。

関連

• Hooks - 内部イベント駆動 hooks と、この HTTP ベースの TaskFlow ブリッジの違い
• Gateway webhooks（hooks.* config） - 別個の汎用 Gateway HTTP エンドポイント機能。この Plugin のルートとは同じではありません
• Plugin runtime SDK
• CLI webhooks