Plugin Webhook

Il Plugin Webhook aggiunge route HTTP autenticate affinché un sistema esterno attendibile (Zapier, n8n, un processo CI, un servizio interno) possa creare e gestire TaskFlow OpenClaw amministrati tramite HTTP, senza scrivere un plugin personalizzato. Il plugin viene eseguito all’interno del processo Gateway. Per un Gateway remoto, installalo e configuralo su tale host, quindi riavvia il Gateway. Viene distribuito senza route configurate, quindi non esegue alcuna operazione finché non aggiungi almeno una route.

Configurare le route

Imposta la configurazione in 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: "Bridge TaskFlow per Zapier",
            },
          },
        },
      },
    },
  },
}

Campi della route:

Campo	Obbligatorio	Valore predefinito	Note
`enabled`	no	`true`
`path`	no	`/plugins/webhooks/<routeId>`	Deve essere univoco tra le route.
`sessionKey`	sì	-	Sessione proprietaria dei TaskFlow associati.
`secret`	sì	-	Stringa semplice o SecretRef (vedi sotto).
`controllerId`	no	`webhooks/<routeId>`	Utilizzato come controller `create_flow` predefinito.
`description`	no	-	Solo una nota per l’operatore.

secret accetta una stringa semplice o un SecretRef: { source: "env" | "file" | "exec", provider: "default", id: "..." }. Ogni route configurata viene registrata all’avvio, indipendentemente dal fatto che il relativo segreto sia attualmente risolvibile. Un segreto non risolvibile non disabilita né ignora la route: le richieste inviate a essa non superano l’autenticazione (401) finché il segreto non può essere risolto. I valori SecretRef vengono risolti nuovamente a ogni richiesta, pertanto la rotazione del segreto sottostante (variabile di ambiente, file o output di un comando) ha effetto senza riavviare il Gateway.

Modello di sicurezza

Ogni route opera con l’autorità TaskFlow della propria sessionKey configurata: può esaminare e modificare qualsiasi TaskFlow appartenente a tale sessione. L’accesso ai TaskFlow avviene sempre tramite api.runtime.tasks.managedFlows.bindSession(...), quindi una route non può mai operare al di fuori della sessione a cui è associata. Per limitare l’impatto:

Usa un segreto robusto e univoco per ogni route.
Preferisci un SecretRef a un segreto in testo non cifrato incorporato.
Associa le route alla sessione più circoscritta compatibile con il flusso di lavoro.
Esponi solo il percorso Webhook specifico necessario.

Ordine di gestione delle richieste per ogni percorso: controlli del metodo HTTP (solo POST) e di Content-Type: application/json, quindi limitazione della frequenza a finestra fissa (120 richieste per finestra di 60 secondi per ogni chiave percorso+IP-client, fino a 4.096 chiavi monitorate), quindi limitazione delle richieste in corso (8 richieste simultanee per chiave, fino a 4.096 chiavi monitorate), quindi autenticazione tramite segreto condiviso, infine lettura del corpo JSON con limite di 256 KB e timeout di 15 secondi. Le richieste che non superano un controllo precedente non raggiungono mai quelli successivi.

Formato della richiesta

Invia richieste POST con Content-Type: application/json e Authorization: Bearer <secret> oppure 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"}'

Azioni supportate

Azione	Scopo
`create_flow`	Crea un TaskFlow amministrato per la sessione della route.
`get_flow`	Recupera un TaskFlow tramite ID.
`list_flows`	Elenca i TaskFlow della sessione della route.
`find_latest_flow`	Recupera il TaskFlow aggiornato più di recente.
`resolve_flow`	Risolve un TaskFlow tramite un token opaco.
`get_task_summary`	Recupera il riepilogo delle attività di un TaskFlow.
`set_waiting`	Contrassegna un TaskFlow come in attesa, con dati facoltativi di stato/attesa.
`resume_flow`	Riprende un TaskFlow in attesa/bloccato.
`finish_flow`	Contrassegna un TaskFlow come completato.
`fail_flow`	Contrassegna un TaskFlow come non riuscito.
`request_cancel`	Richiede l’annullamento cooperativo.
`cancel_flow`	Annulla un TaskFlow (può restituire `202` se le attività figlie sono ancora attive).
`run_task`	Crea un’attività figlia amministrata all’interno di un TaskFlow esistente.

Le azioni di modifica (set_waiting, resume_flow, finish_flow, fail_flow, request_cancel) richiedono flowId ed expectedRevision per la concorrenza ottimistica; una revisione obsoleta restituisce 409 revision_conflict.

`create_flow`

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

`run_task`

Valori runtime consentiti: subagent, acp. startedAt, lastEventAt e progressSummary sono validi solo quando status è "running"; inviarli con qualsiasi altro stato restituisce 400 invalid_request.

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

Struttura della risposta

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

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

Le viste dei flussi e delle attività non includono mai metadati relativi al proprietario o alla sessione, pertanto le risposte non possono esporre la sessionKey associata alla route. I valori di code includono not_found, not_managed, revision_conflict, persist_failed, cancel_requested, cancel_pending, terminal, invalid_request, request_rejected e codici di riserva specifici delle azioni (mutation_rejected, create_rejected, task_not_created, cancel_rejected) quando una modifica viene rifiutata per un motivo non contemplato dai codici indicati sopra.

Contenuti correlati

Hook - hook interni basati su eventi rispetto a questo bridge TaskFlow basato su HTTP
Webhook del Gateway (configurazione hooks.*) - funzionalità separata per endpoint HTTP generici del Gateway; non corrisponde alle route di questo plugin
SDK di runtime dei plugin
Webhook della CLI

Overview

Plugins

Plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

Configurare le route

Modello di sicurezza

Formato della richiesta

Azioni supportate

`create_flow`

`run_task`

Struttura della risposta

Contenuti correlati

​Configurare le route

​Modello di sicurezza

​Formato della richiesta

​Azioni supportate

​create_flow

​run_task

​Struttura della risposta

​Contenuti correlati

Configurare le route

Modello di sicurezza

Formato della richiesta

Azioni supportate

`create_flow`

`run_task`

Struttura della risposta

Contenuti correlati