Webhooks plugin

Webhooks (plugin)

The Webhooks plugin adds authenticated HTTP routes that bind external automation to OpenClaw TaskFlows.

Use it when you want a trusted system such as Zapier, n8n, a CI job, or an internal service to create and drive managed TaskFlows without writing a custom plugin first.

Where it runs

The Webhooks plugin runs inside the Gateway process.

If your Gateway runs on another machine, install and configure the plugin on that Gateway host, then restart the Gateway.

Configure routes

Set config under

:

json5
Copy
{
  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",
            },
          },
        },
      },
    },
  },
}

Route fields:

• text

  Copy

  enabled
  : optional, defaults to
  text

  Copy

  true
• text

  Copy

  path
  : optional, defaults to
  text

  Copy

  /plugins/webhooks/<routeId>
• text

  Copy

  sessionKey
  : required session that owns the bound TaskFlows
• text

  Copy

  secret
  : required shared secret or SecretRef
• text

  Copy

  controllerId
  : optional controller id for created managed flows
• text

  Copy

  description
  : optional operator note

Supported

inputs:

• Plain string
• SecretRef with
  text

  Copy

  source: "env" | "file" | "exec"

If a secret-backed route cannot resolve its secret at startup, the plugin skips that route and logs a warning instead of exposing a broken endpoint.

Security model

Each route is trusted to act with the TaskFlow authority of its configured

.

This means the route can inspect and mutate TaskFlows owned by that session, so you should:

• Use a strong unique secret per route
• Prefer secret references over inline plaintext secrets
• Bind routes to the narrowest session that fits the workflow
• Expose only the specific webhook path you need

The plugin applies:

• Shared-secret authentication
• Request body size and timeout guards
• Fixed-window rate limiting
• In-flight request limiting
• Owner-bound TaskFlow access through
  text

  Copy

  api.runtime.tasks.managedFlows.bindSession(...)

Request format

Send

requests with:

• text

  Copy

  Content-Type: application/json
• text

  Copy

  Authorization: Bearer <secret>
  or
  text

  Copy

  x-openclaw-webhook-secret: <secret>

Example:

bash
Copy
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"}'

Supported actions

The plugin currently accepts these JSON

values:

• text

  Copy

  create_flow
• text

  Copy

  get_flow
• text

  Copy

  list_flows
• text

  Copy

  find_latest_flow
• text

  Copy

  resolve_flow
• text

  Copy

  get_task_summary
• text

  Copy

  set_waiting
• text

  Copy

  resume_flow
• text

  Copy

  finish_flow
• text

  Copy

  fail_flow
• text

  Copy

  request_cancel
• text

  Copy

  cancel_flow
• text

  Copy

  run_task

text

Copy

create_flow

Creates a managed TaskFlow for the route's bound session.

Example:

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

text

Copy

run_task

Creates a managed child task inside an existing managed TaskFlow.

Allowed runtimes are:

• text

  Copy

  subagent
• text

  Copy

  acp

Example:

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

Response shape

Successful responses return:

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

Rejected requests return:

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

The plugin intentionally scrubs owner/session metadata from webhook responses.

Related docs

• Plugin runtime SDK
• Hooks and webhooks overview
• CLI webhooks