Webhooks plugin

Webhooks plugin 문서는 OpenClaw 공식 문서(plugins/webhooks)를 한국어로 정리한 가이드입니다. Webhooks plugin: authenticated TaskFlow ingress for trusted external automation 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Webhooks plugin: authenticated TaskFlow ingress for trusted external automation

한국어 가이드 범위: plugins/webhooks 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Configure routes
Security model
Request format
Supported actions
create_flow
run_task
Response shape
관련 문서

상세 내용

본문

The Webhooks plugin adds authenticated HTTP routes so a trusted external system (Zapier, n8n, a CI job, an internal service) can create and drive managed OpenClaw TaskFlows over HTTP, without writing a custom plugin.

Configure routes

Set config under plugins.entries.webhooks.config:

Field	Required	Default	Notes
`enabled`	no	`true`
`path`	no	`/plugins/webhooks/<routeId>`	Must be unique across routes.
`sessionKey`	yes	-	Session that owns the bound TaskFlows.
`secret`	yes	-	Plain string or a SecretRef (below).
`controllerId`	no	`webhooks/<routeId>`	Used as the default `create_flow` controller.
`description`	no	-	Operator note only.

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

Security model

Each route acts with the TaskFlow authority of its configured sessionKey: it can inspect and mutate any TaskFlow owned by that session. TaskFlow access always goes through api.runtime.tasks.managedFlows.bindSession(...), so a route can never act outside its bound session. To limit blast radius:

주요 항목:

Use a strong, unique secret per route.
Prefer a SecretRef over an inline plaintext secret.
Bind routes to the narrowest session that fits the workflow.
Expose only the specific webhook path you need.

Request format

Send POST requests with Content-Type: application/json and either Authorization: Bearer or x-openclaw-webhook-secret: :

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

Mutating actions (set_waiting, resume_flow, finish_flow, fail_flow, request_cancel) require flowId and expectedRevision for optimistic concurrency; a stale revision returns 409 revision_conflict.

Action	Purpose
`create_flow`	Create a managed TaskFlow for the route's session.
`get_flow`	Fetch one TaskFlow by id.
`list_flows`	List TaskFlows for the route's session.
`find_latest_flow`	Fetch the most recently updated TaskFlow.
`resolve_flow`	Resolve a TaskFlow by opaque token.
`get_task_summary`	Fetch the task summary for a TaskFlow.
`set_waiting`	Mark a TaskFlow waiting, with optional state/wait data.
`resume_flow`	Resume a waiting/blocked TaskFlow.
`finish_flow`	Mark a TaskFlow finished.
`fail_flow`	Mark a TaskFlow failed.
`request_cancel`	Request cooperative cancellation.
`cancel_flow`	Cancel a TaskFlow (may return `202` if children are still active).
`run_task`	Create a managed child task inside an existing TaskFlow.

create_flow

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

run_task

Allowed runtime values: subagent, acp. startedAt, lastEventAt, and progressSummary are only valid when status is "running"; sending them with any other status returns 400 invalid_request.

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

Response shape

Flow and task views never include owner/session metadata, so responses cannot leak the route's bound sessionKey. code values include not_found, not_managed, revision_conflict, persist_failed, cancel_requested, cancel_pending, terminal, invalid_request, request_rejected, and action-specific fallback codes (mutation_rejected, create_rejected, task_not_created, cancel_rejected) when a mutation is rejected for a reason not covered by the named codes above.

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

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

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/plugins/webhooks
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

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

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

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

{
  "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": {}
}

Webhooks plugin

핵심 요약

Webhooks plugin: authenticated TaskFlow ingress for trusted external automation

한국어 가이드 범위: plugins/webhooks 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Configure routes
Security model
Request format
Supported actions
create_flow
run_task
Response shape
관련 문서

상세 내용

본문

Configure routes

Set config under plugins.entries.webhooks.config:

Field	Required	Default	Notes
`enabled`	no	`true`
`path`	no	`/plugins/webhooks/<routeId>`	Must be unique across routes.
`sessionKey`	yes	-	Session that owns the bound TaskFlows.
`secret`	yes	-	Plain string or a SecretRef (below).
`controllerId`	no	`webhooks/<routeId>`	Used as the default `create_flow` controller.
`description`	no	-	Operator note only.

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

Security model

주요 항목:

Use a strong, unique secret per route.
Prefer a SecretRef over an inline plaintext secret.
Bind routes to the narrowest session that fits the workflow.
Expose only the specific webhook path you need.

Request format

Send POST requests with Content-Type: application/json and either Authorization: Bearer or x-openclaw-webhook-secret: :

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

Action	Purpose
`create_flow`	Create a managed TaskFlow for the route's session.
`get_flow`	Fetch one TaskFlow by id.
`list_flows`	List TaskFlows for the route's session.
`find_latest_flow`	Fetch the most recently updated TaskFlow.
`resolve_flow`	Resolve a TaskFlow by opaque token.
`get_task_summary`	Fetch the task summary for a TaskFlow.
`set_waiting`	Mark a TaskFlow waiting, with optional state/wait data.
`resume_flow`	Resume a waiting/blocked TaskFlow.
`finish_flow`	Mark a TaskFlow finished.
`fail_flow`	Mark a TaskFlow failed.
`request_cancel`	Request cooperative cancellation.
`cancel_flow`	Cancel a TaskFlow (may return `202` if children are still active).
`run_task`	Create a managed child task inside an existing TaskFlow.

create_flow

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

run_task

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

Response shape

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

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

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/plugins/webhooks
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

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

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

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

{
  "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": {}
}

Webhooks plugin

핵심 요약

문서 구성

상세 내용

본문

Configure routes

Security model

Request format

Supported actions

create_flow

run_task

Response shape

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Webhooks plugin

핵심 요약

문서 구성

상세 내용

본문

Configure routes

Security model

Request format

Supported actions

create_flow

run_task

Response shape

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드