Webhook Plugin

Webhooks Plugin은 신뢰할 수 있는 외부 시스템(Zapier, n8n, CI 작업, 내부 서비스)이 사용자 지정 Plugin을 작성하지 않고도 HTTP를 통해 관리형 OpenClaw TaskFlow를 생성하고 제어할 수 있도록 인증된 HTTP 경로를 추가합니다.

이 Plugin은 Gateway 프로세스 내부에서 실행됩니다. 원격 Gateway의 경우 해당 호스트에 설치하고 구성한 다음 Gateway를 다시 시작하세요. 기본적으로 구성된 경로가 없으므로 경로를 하나 이상 추가하기 전까지는 아무 작업도 수행하지 않습니다.

경로 구성

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 값은 요청할 때마다 다시 확인되므로 기반 비밀 값(환경 변수, 파일 또는 실행 결과)을 교체하면 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개 키 추적), 공유 비밀 인증, 256KB/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