Plugin Webhooków

Plugin Webhooks dodaje uwierzytelnione trasy HTTP, dzięki którym zaufany system zewnętrzny (Zapier, n8n, zadanie CI, usługa wewnętrzna) może tworzyć i sterować zarządzanymi TaskFlows OpenClaw przez HTTP bez pisania niestandardowego pluginu.

Plugin działa wewnątrz procesu Gateway. W przypadku zdalnego Gateway zainstaluj i skonfiguruj go na tym hoście, a następnie uruchom ponownie Gateway. Domyślnie nie ma skonfigurowanych żadnych tras, więc nie wykonuje żadnych działań, dopóki nie dodasz co najmniej jednej trasy.

Konfigurowanie tras

Ustaw konfigurację w 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",            },          },        },      },    },  },}

Pola trasy:

secret przyjmuje zwykły ciąg znaków lub SecretRef: { source: "env" | "file" | "exec", provider: "default", id: "..." }.

Każda skonfigurowana trasa jest rejestrowana podczas uruchamiania niezależnie od tego, czy jej sekret można w danej chwili rozpoznać. Sekret, którego nie można rozpoznać, nie wyłącza ani nie pomija trasy — żądania do niej nie przechodzą uwierzytelniania (401), dopóki rozpoznanie sekretu nie stanie się możliwe. Wartości SecretRef są rozpoznawane ponownie przy każdym żądaniu, więc rotacja źródłowego sekretu (zmiennej środowiskowej, pliku lub wyniku polecenia) zaczyna obowiązywać bez ponownego uruchamiania Gateway.

Model zabezpieczeń

Każda trasa działa z uprawnieniami TaskFlow skonfigurowanego sessionKey: może sprawdzać i modyfikować dowolny TaskFlow należący do tej sesji. Dostęp do TaskFlow zawsze odbywa się przez api.runtime.tasks.managedFlows.bindSession(...), dlatego trasa nigdy nie może działać poza powiązaną sesją. Aby ograniczyć zasięg potencjalnych szkód:

• Używaj silnego, unikatowego sekretu dla każdej trasy.
• Preferuj SecretRef zamiast jawnego sekretu umieszczonego bezpośrednio w konfiguracji.
• Powiąż trasy z sesją o najwęższym zakresie odpowiednim dla przepływu pracy.
• Udostępniaj tylko konkretną ścieżkę Webhooka, której potrzebujesz.

Kolejność obsługi żądania dla każdej ścieżki: sprawdzenie metody HTTP (wyłącznie POST) i Content-Type: application/json, następnie ograniczenie częstotliwości w stałym oknie (120 żądań na 60-sekundowe okno dla każdego klucza ścieżka+adres-IP-klienta, maksymalnie 4096 śledzonych kluczy), następnie ograniczenie liczby trwających żądań (8 równoczesnych żądań na klucz, maksymalnie 4096 śledzonych kluczy), następnie uwierzytelnienie współdzielonym sekretem, a na końcu odczyt treści JSON z limitem 256 KB i 15 sekund. Żądania, które nie przejdą wcześniejszej kontroli, nigdy nie docierają do kolejnych.

Format żądania

Wysyłaj żądania POST z Content-Type: application/json oraz nagłówkiem Authorization: Bearer <secret> albo 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"}'

Obsługiwane akcje

Akcje modyfikujące (set_waiting, resume_flow, finish_flow, fail_flow, request_cancel) wymagają pól flowId i expectedRevision do optymistycznej kontroli współbieżności; nieaktualna rewizja powoduje zwrócenie 409 revision_conflict.

create_flow

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

run_task

Dozwolone wartości runtime: subagent, acp. Pola startedAt, lastEventAt i progressSummary są prawidłowe tylko wtedy, gdy status ma wartość "running"; wysłanie ich z dowolnym innym statusem powoduje zwrócenie 400 invalid_request.

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

Struktura odpowiedzi

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

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

Widoki przepływów i zadań nigdy nie zawierają metadanych właściciela ani sesji, dlatego odpowiedzi nie mogą ujawnić powiązanego z trasą sessionKey. Wartości code obejmują not_found, not_managed, revision_conflict, persist_failed, cancel_requested, cancel_pending, terminal, invalid_request, request_rejected oraz kody rezerwowe specyficzne dla akcji (mutation_rejected, create_rejected, task_not_created, cancel_rejected), gdy modyfikacja zostanie odrzucona z powodu nieobjętego wymienionymi wyżej kodami.

Powiązane materiały

• Hooki — wewnętrzne hooki sterowane zdarzeniami w porównaniu z tym mostem TaskFlow opartym na HTTP
• Webhooki Gateway (konfiguracja hooks.*) — oddzielna, ogólna funkcja punktu końcowego HTTP Gateway; nie jest tym samym co trasy tego pluginu
• SDK środowiska uruchomieniowego pluginów
• Webhooki CLI