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:

Feld	Erforderlich	Standardwert	Hinweise
`enabled`	nein	`true`
`path`	nein	`/plugins/webhooks/<routeId>`	Muss über alle Routen hinweg eindeutig sein.
`sessionKey`	ja	-	Sitzung, der die gebundenen TaskFlows gehören.
`secret`	ja	-	Einfache Zeichenfolge oder eine SecretRef (siehe unten).
`controllerId`	nein	`webhooks/<routeId>`	Wird als standardmäßiger `create_flow`-Controller verwendet.
`description`	nein	-	Nur ein Hinweis für den Betreiber.

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

Aktion	Zweck
`create_flow`	Erstellt einen verwalteten TaskFlow für die Sitzung der Route.
`get_flow`	Ruft einen TaskFlow anhand seiner ID ab.
`list_flows`	Listet TaskFlows für die Sitzung der Route auf.
`find_latest_flow`	Ruft den zuletzt aktualisierten TaskFlow ab.
`resolve_flow`	Löst einen TaskFlow anhand eines opaken Tokens auf.
`get_task_summary`	Ruft die Aufgabenzusammenfassung eines TaskFlows ab.
`set_waiting`	Markiert einen TaskFlow als wartend, optional mit Status-/Wartedaten.
`resume_flow`	Setzt einen wartenden/blockierten TaskFlow fort.
`finish_flow`	Markiert einen TaskFlow als abgeschlossen.
`fail_flow`	Markiert einen TaskFlow als fehlgeschlagen.
`request_cancel`	Fordert kooperative Abbrechung an.
`cancel_flow`	Bricht einen TaskFlow ab (kann `202` zurückgeben, wenn untergeordnete Abläufe noch aktiv sind).
`run_task`	Erstellt eine verwaltete untergeordnete Aufgabe innerhalb eines vorhandenen TaskFlows.

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.

Overview

Plugins

Plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

Routen konfigurieren

Sicherheitsmodell

Anfrageformat

Unterstützte Aktionen

`create_flow`

`run_task`

Antwortstruktur

Verwandte Themen

​Routen konfigurieren

​Sicherheitsmodell

​Anfrageformat

​Unterstützte Aktionen

​create_flow

​run_task

​Antwortstruktur

​Verwandte Themen

Routen konfigurieren

Sicherheitsmodell

Anfrageformat

Unterstützte Aktionen

`create_flow`

`run_task`

Antwortstruktur

Verwandte Themen