Webhooks-Plugin

Das Webhooks-Plugin fügt authentifizierte HTTP-Routen hinzu, damit ein vertrauenswürdiges externes System (Zapier, n8n, ein CI-Auftrag, ein interner Dienst) verwaltete OpenClaw-TaskFlows über HTTP erstellen und steuern kann, ohne ein benutzerdefiniertes Plugin zu schreiben.

Das Plugin wird im Gateway-Prozess ausgeführt. Bei einem entfernten Gateway installieren und konfigurieren Sie es auf diesem Host und starten anschließend das Gateway neu. Es wird ohne konfigurierte Routen ausgeliefert und bleibt daher wirkungslos, bis Sie mindestens eine Route hinzufügen.

Routen konfigurieren

Legen Sie die Konfiguration unter plugins.entries.webhooks.config fest:

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

Routenfelder:

secret akzeptiert eine einfache Zeichenfolge oder eine SecretRef: { source: "env" | "file" | "exec", provider: "default", id: "..." }.

SecretRefs werden im Startkonfigurations-Snapshot des Gateways aufgelöst. Wenn das Secret einer Route nicht aufgelöst werden kann, läuft das Gateway weiter und genau diese Route bleibt registriert, aber inaktiv: Anfragen erhalten einen generischen Authentifizierungsfehler (401). Andere Routen bleiben verfügbar. Korrigieren Sie die SecretRef-Quelle und laden Sie anschließend das Gateway neu oder starten Sie es neu, um den neuen Snapshot zu aktivieren. SecretRef-Werte werden im öffentlichen Anfragepfad niemals aufgelöst.

Sicherheitsmodell

Jede Route agiert mit der TaskFlow-Berechtigung ihres konfigurierten sessionKey: Sie kann jeden TaskFlow prüfen und verändern, der dieser Sitzung gehört. Der TaskFlow-Zugriff erfolgt immer über api.runtime.tasks.managedFlows.bindSession(...), sodass eine Route niemals außerhalb ihrer gebundenen Sitzung agieren kann. So begrenzen Sie den potenziellen Schadensradius:

• Verwenden Sie für jede Route ein starkes, eindeutiges Secret.
• Bevorzugen Sie eine SecretRef gegenüber einem eingebetteten Klartext-Secret.
• Binden Sie Routen an die kleinstmögliche Sitzung, die für den Arbeitsablauf ausreicht.
• Machen Sie nur den konkret benötigten Webhook-Pfad zugänglich.

Reihenfolge der Anfrageverarbeitung für jeden Pfad: Prüfungen der HTTP-Methode (nur POST) und von Content-Type: application/json, dann Ratenbegrenzung mit festem Zeitfenster (120 Anfragen pro 60-Sekunden-Fenster und Pfad+Client-IP-Schlüssel, bis zu 4,096 erfasste Schlüssel), dann Begrenzung gleichzeitig verarbeiteter Anfragen (8 gleichzeitige Anfragen pro Schlüssel, bis zu 4,096 erfasste Schlüssel), dann Authentifizierung mit gemeinsamem Secret und anschließend das Einlesen eines JSON-Bodys mit 256 KB / 15 Sekunden. Anfragen, die bei einer früheren Prüfung scheitern, erreichen die späteren Prüfungen nicht.

Anfrageformat

Senden Sie POST-Anfragen mit Content-Type: application/json und entweder Authorization: Bearer <secret> oder 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":"Eingangswarteschlange prüfen"}'

Unterstützte Aktionen

Verändernde Aktionen (set_waiting, resume_flow, finish_flow, fail_flow, request_cancel) erfordern für optimistische Nebenläufigkeit flowId und expectedRevision; eine veraltete Revision gibt 409 revision_conflict zurück.

create_flow

{  "action": "create_flow",  "goal": "Eingangswarteschlange prüfen",  "status": "queued",  "notifyPolicy": "done_only"}

run_task

Zulässige runtime-Werte: subagent, acp. startedAt, lastEventAt und progressSummary sind nur gültig, wenn status den Wert "running" hat; werden sie mit einem anderen Status gesendet, wird 400 invalid_request zurückgegeben.

{  "action": "run_task",  "flowId": "flow_123",  "runtime": "acp",  "childSessionKey": "agent:main:acp:worker",  "task": "Nächsten Nachrichtenstapel prüfen"}

Antwortstruktur

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

{  "ok": false,  "routeId": "zapier",  "code": "not_found",  "error": "TaskFlow nicht gefunden.",  "result": {}}

Ablauf- und Aufgabenansichten enthalten niemals Eigentümer-/Sitzungsmetadaten, sodass Antworten den gebundenen sessionKey der Route nicht offenlegen können. Zu den code-Werten gehören not_found, not_managed, revision_conflict, persist_failed, cancel_requested, cancel_pending, terminal, invalid_request, request_rejected und aktionsspezifische Rückfallcodes (mutation_rejected, create_rejected, task_not_created, cancel_rejected), wenn eine Änderung aus einem Grund abgelehnt wird, der nicht von den oben genannten Codes abgedeckt ist.

Verwandte Themen

• Hooks – interne ereignisgesteuerte Hooks im Vergleich zu dieser HTTP-basierten TaskFlow-Bridge
• Gateway-Webhooks (hooks.*-Konfiguration) – separate generische Funktion für HTTP-Endpunkte des Gateways; nicht identisch mit den Routen dieses Plugins
• Plugin-Laufzeit-SDK
• CLI-Webhooks