Plugin Webhook

Plugin Webhooks bổ sung các tuyến HTTP có xác thực để một hệ thống bên ngoài đáng tin cậy (Zapier, n8n, tác vụ CI, dịch vụ nội bộ) có thể tạo và điều khiển các TaskFlow được OpenClaw quản lý qua HTTP mà không cần viết plugin tùy chỉnh.

Plugin chạy bên trong tiến trình Gateway. Với Gateway từ xa, hãy cài đặt và cấu hình plugin trên máy chủ đó, sau đó khởi động lại Gateway. Plugin không đi kèm tuyến nào được cấu hình, nên sẽ không làm gì cho đến khi bạn thêm ít nhất một tuyến.

Cấu hình tuyến

Đặt cấu hình trong 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: "Cầu nối TaskFlow của Zapier",            },          },        },      },    },  },}

Các trường của tuyến:

secret chấp nhận một chuỗi thuần túy hoặc SecretRef: { source: "env" | "file" | "exec", provider: "default", id: "..." }.

Mọi tuyến đã cấu hình đều được đăng ký khi khởi động, bất kể bí mật của tuyến hiện có phân giải được hay không. Bí mật không thể phân giải không vô hiệu hóa hoặc bỏ qua tuyến — các yêu cầu đến tuyến đó sẽ không xác thực được (401) cho đến khi bí mật có thể được phân giải. Các giá trị SecretRef được phân giải lại trong mỗi yêu cầu, vì vậy việc luân chuyển bí mật cơ sở (biến môi trường, tệp hoặc đầu ra lệnh thực thi) có hiệu lực mà không cần khởi động lại Gateway.

Mô hình bảo mật

Mỗi tuyến hoạt động với quyền TaskFlow của sessionKey đã cấu hình: tuyến có thể kiểm tra và thay đổi mọi TaskFlow thuộc sở hữu của phiên đó. Quyền truy cập TaskFlow luôn đi qua api.runtime.tasks.managedFlows.bindSession(...), vì vậy tuyến không bao giờ có thể hoạt động bên ngoài phiên được liên kết. Để giới hạn phạm vi ảnh hưởng:

• Sử dụng một bí mật mạnh và duy nhất cho mỗi tuyến.
• Ưu tiên SecretRef thay vì bí mật văn bản thuần túy nội tuyến.
• Liên kết tuyến với phiên có phạm vi hẹp nhất phù hợp với quy trình làm việc.
• Chỉ công khai đường dẫn Webhook cụ thể mà bạn cần.

Thứ tự xử lý yêu cầu cho mỗi đường dẫn: kiểm tra phương thức HTTP (chỉ POST) và Content-Type: application/json, sau đó giới hạn tốc độ theo cửa sổ cố định (120 yêu cầu trong mỗi cửa sổ 60 giây cho từng khóa đường-dẫn+IP-máy-khách, theo dõi tối đa 4.096 khóa), tiếp theo là giới hạn yêu cầu đang xử lý (8 yêu cầu đồng thời cho mỗi khóa, theo dõi tối đa 4.096 khóa), rồi xác thực bằng bí mật dùng chung, cuối cùng là đọc phần thân JSON tối đa 256 KB trong 15 giây. Các yêu cầu không vượt qua bước kiểm tra trước đó sẽ không bao giờ đến được các bước sau.

Định dạng yêu cầu

Gửi yêu cầu POST với Content-Type: application/json và Authorization: Bearer <secret> hoặc x-openclaw-webhook-secret: <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"}'

Các hành động được hỗ trợ

Các hành động thay đổi (set_waiting, resume_flow, finish_flow, fail_flow, request_cancel) yêu cầu flowId và expectedRevision để kiểm soát đồng thời lạc quan; bản sửa đổi cũ trả về 409 revision_conflict.

create_flow

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

run_task

Các giá trị runtime được phép: subagent, acp. startedAt, lastEventAt và progressSummary chỉ hợp lệ khi status là "running"; gửi chúng với bất kỳ trạng thái nào khác sẽ trả về 400 invalid_request.

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

Cấu trúc phản hồi

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

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

Chế độ xem luồng và tác vụ không bao giờ chứa siêu dữ liệu về chủ sở hữu/phiên, vì vậy phản hồi không thể làm lộ sessionKey được liên kết của tuyến. Các giá trị code bao gồm not_found, not_managed, revision_conflict, persist_failed, cancel_requested, cancel_pending, terminal, invalid_request, request_rejected và các mã dự phòng dành riêng cho từng hành động (mutation_rejected, create_rejected, task_not_created, cancel_rejected) khi một thao tác thay đổi bị từ chối vì lý do không thuộc các mã đã nêu ở trên.

Liên quan

• Hooks - hook nội bộ được kích hoạt theo sự kiện so với cầu nối TaskFlow dựa trên HTTP này
• Webhook của Gateway (cấu hình hooks.*) - tính năng điểm cuối HTTP chung riêng biệt của Gateway; không giống các tuyến của plugin này
• SDK thời gian chạy của plugin
• Webhook CLI