English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Plugins

Webhooks-Plugin

Das Webhooks-Plugin fügt authentifizierte HTTP-Routen hinzu, die externe Automatisierung an OpenClaw TaskFlows binden.

Verwenden Sie es, wenn ein vertrauenswürdiges System wie Zapier, n8n, ein CI-Job oder ein interner Dienst verwaltete TaskFlows erstellen und steuern soll, ohne zuerst ein eigenes Plugin schreiben zu müssen.

Wo es ausgeführt wird

Das Webhooks-Plugin wird im Gateway-Prozess ausgeführt.

Wenn Ihr Gateway auf einem anderen Computer läuft, installieren und konfigurieren Sie das Plugin auf diesem Gateway-Host und starten Sie anschließend das Gateway neu.

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:

  • enabled: optional, Standardwert ist true
  • path: optional, Standardwert ist /plugins/webhooks/<routeId>
  • sessionKey: erforderliche Sitzung, der die gebundenen TaskFlows gehören
  • secret: erforderliches gemeinsames Secret oder SecretRef
  • controllerId: optionale Controller-ID für erstellte verwaltete Flows
  • description: optionale Betreibernotiz

Unterstützte secret-Eingaben:

  • Klartextzeichenfolge
  • SecretRef mit source: "env" | "file" | "exec"

Wenn eine Secret-gestützte Route ihr Secret beim Start nicht auflösen kann, überspringt das Plugin diese Route und protokolliert eine Warnung, statt einen fehlerhaften Endpunkt offenzulegen.

Sicherheitsmodell

Jede Route gilt als vertrauenswürdig, mit der TaskFlow-Autorität ihres konfigurierten sessionKey zu handeln.

Das bedeutet, dass die Route TaskFlows prüfen und ändern kann, die dieser Sitzung gehören. Daher sollten Sie:

  • Pro Route ein starkes eindeutiges Secret verwenden
  • Secret-Referenzen gegenüber Inline-Klartext-Secrets bevorzugen
  • Routen an die engste Sitzung binden, die zum Workflow passt
  • Nur den spezifischen Webhook-Pfad freigeben, den Sie benötigen

Das Plugin wendet Folgendes an:

  • Authentifizierung über gemeinsames Secret
  • Schutzmechanismen für Größe und Timeout des Anfragebodys
  • Ratenbegrenzung mit festem Zeitfenster
  • Begrenzung paralleler laufender Anfragen
  • Eigentümergebundener TaskFlow-Zugriff über api.runtime.tasks.managedFlows.bindSession(...)

Anfrageformat

Senden Sie POST-Anfragen mit:

  • Content-Type: application/json
  • Authorization: Bearer <secret> oder x-openclaw-webhook-secret: <secret>

Beispiel:

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"}'

Unterstützte Aktionen

Das Plugin akzeptiert derzeit diese JSON-action-Werte:

  • create_flow
  • get_flow
  • list_flows
  • find_latest_flow
  • resolve_flow
  • get_task_summary
  • set_waiting
  • resume_flow
  • finish_flow
  • fail_flow
  • request_cancel
  • cancel_flow
  • run_task

create_flow

Erstellt einen verwalteten TaskFlow für die gebundene Sitzung der Route.

Beispiel:

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

run_task

Erstellt eine verwaltete untergeordnete Aufgabe innerhalb eines vorhandenen verwalteten TaskFlow.

Zulässige Laufzeitumgebungen sind:

  • subagent
  • acp

Beispiel:

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

Antwortform

Erfolgreiche Antworten geben zurück:

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

Abgelehnte Anfragen geben zurück:

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

Das Plugin entfernt absichtlich Eigentümer- und Sitzungsmetadaten aus Webhook-Antworten.

Verwandte Dokumentation