メインコンテンツへスキップ
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",
            },
          },
        },
      },
    },
  },
}
ルートのフィールド:
フィールド必須デフォルト備考
enablednotrue
pathno/plugins/webhooks/<routeId>ルート間で一意である必要があります。
sessionKeyyes-バインドされた TaskFlows を所有するセッション。
secretyes-プレーン文字列または SecretRef（下記）。
controllerIdnowebhooks/<routeId>デフォルトの create_flow コントローラーとして使用されます。
descriptionno-オペレーター向けメモのみ。
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"}'

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

アクション目的
create_flowルートのセッション用にマネージド TaskFlow を作成します。
get_flowid で 1 つの TaskFlow を取得します。
list_flowsルートのセッションの TaskFlows を一覧表示します。
find_latest_flow直近に更新された TaskFlow を取得します。
resolve_flow不透明トークンで TaskFlow を解決します。
get_task_summaryTaskFlow のタスク概要を取得します。
set_waiting任意の state/wait データ付きで TaskFlow を待機中にします。
resume_flow待機中またはブロック中の TaskFlow を再開します。
finish_flowTaskFlow を完了としてマークします。
fail_flowTaskFlow を失敗としてマークします。
request_cancel協調的キャンセルをリクエストします。
cancel_flowTaskFlow をキャンセルします（子がまだアクティブな場合は 202 を返すことがあります）。
run_task既存の TaskFlow 内にマネージド子タスクを作成します。
変更を行うアクション（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）が含まれます。

​
関連