Plugin de Webhooks

O Plugin Webhooks adiciona rotas HTTP autenticadas para que um sistema externo confiável (Zapier, n8n, uma tarefa de CI, um serviço interno) possa criar e controlar TaskFlows gerenciados do OpenClaw por HTTP, sem escrever um plugin personalizado.

O plugin é executado dentro do processo do Gateway. Para um Gateway remoto, instale-o e configure-o nesse host e, em seguida, reinicie o Gateway. Ele é fornecido sem nenhuma rota configurada, portanto, não faz nada até que você adicione pelo menos uma rota.

Configurar rotas

Defina a configuração em 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: "Ponte de TaskFlow para o Zapier",            },          },        },      },    },  },}

Campos da rota:

secret aceita uma string simples ou uma SecretRef: { source: "env" | "file" | "exec", provider: "default", id: "..." }.

Cada rota configurada é registrada na inicialização, independentemente de seu segredo poder ser resolvido naquele momento. Um segredo que não pode ser resolvido não desabilita nem ignora a rota — as solicitações feitas a ela falham na autenticação (401) até que o segredo possa ser resolvido. Os valores de SecretRef são resolvidos novamente a cada solicitação, portanto, a rotação do segredo subjacente (variável de ambiente, arquivo ou saída de execução) entra em vigor sem reiniciar o Gateway.

Modelo de segurança

Cada rota atua com a autoridade de TaskFlow da sessionKey configurada: ela pode inspecionar e alterar qualquer TaskFlow pertencente a essa sessão. O acesso ao TaskFlow sempre passa por api.runtime.tasks.managedFlows.bindSession(...), portanto, uma rota nunca pode atuar fora de sua sessão vinculada. Para limitar o raio de impacto:

• Use um segredo forte e exclusivo para cada rota.
• Prefira uma SecretRef a um segredo em texto simples embutido.
• Vincule as rotas à sessão mais restrita que atenda ao fluxo de trabalho.
• Exponha somente o caminho de Webhook específico necessário.

Ordem de processamento das solicitações para cada caminho: verificações do método HTTP (somente POST) e de Content-Type: application/json, seguidas pela limitação de taxa com janela fixa (120 solicitações por janela de 60 segundos para cada chave de caminho+IP-do-cliente, com até 4.096 chaves rastreadas), pela limitação de solicitações em andamento (8 solicitações simultâneas por chave, com até 4.096 chaves rastreadas), pela autenticação com segredo compartilhado e, por fim, pela leitura do corpo JSON, limitada a 256 KB e 15 segundos. Solicitações que falham em uma verificação anterior nunca chegam às verificações posteriores.

Formato da solicitação

Envie solicitações POST com Content-Type: application/json e Authorization: Bearer <secret> ou 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"}'

Ações compatíveis

As ações de alteração (set_waiting, resume_flow, finish_flow, fail_flow, request_cancel) exigem flowId e expectedRevision para controle de concorrência otimista; uma revisão desatualizada retorna 409 revision_conflict.

create_flow

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

run_task

Valores permitidos para runtime: subagent, acp. startedAt, lastEventAt e progressSummary só são válidos quando status é "running"; enviá-los com qualquer outro status retorna 400 invalid_request.

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

Formato da resposta

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

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

As visualizações de fluxos e tarefas nunca incluem metadados do proprietário ou da sessão, portanto, as respostas não podem vazar a sessionKey vinculada à rota. Os valores de code incluem not_found, not_managed, revision_conflict, persist_failed, cancel_requested, cancel_pending, terminal, invalid_request, request_rejected e códigos alternativos específicos da ação (mutation_rejected, create_rejected, task_not_created, cancel_rejected) quando uma alteração é rejeitada por um motivo não abrangido pelos códigos nomeados acima.

Relacionados

• Hooks — hooks internos orientados a eventos em comparação com esta ponte de TaskFlow baseada em HTTP
• Webhooks do Gateway (configuração hooks.*) — recurso separado de endpoint HTTP genérico do Gateway; não é o mesmo que as rotas deste plugin
• SDK de runtime do plugin
• Webhooks da CLI