Plugin de Webhooks

El plugin Webhooks añade rutas HTTP autenticadas para que un sistema externo de confianza (Zapier, n8n, un trabajo de CI, un servicio interno) pueda crear y controlar TaskFlows administrados de OpenClaw mediante HTTP, sin escribir un plugin personalizado.

El plugin se ejecuta dentro del proceso del Gateway. Para un Gateway remoto, instálelo y configúrelo en ese host y, después, reinicie el Gateway. Se distribuye sin rutas configuradas, por lo que no hace nada hasta que se añade al menos una ruta.

Configurar rutas

Establezca la configuración en 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: "Puente de TaskFlow para Zapier",            },          },        },      },    },  },}

Campos de ruta:

secret acepta una cadena de texto sin formato o una SecretRef: { source: "env" | "file" | "exec", provider: "default", id: "..." }.

Las SecretRefs se resuelven en la instantánea de configuración de inicio del Gateway. Cuando el secreto de una ruta no se puede resolver, el Gateway continúa ejecutándose y esa ruta específica permanece registrada pero inactiva: las solicitudes reciben un error genérico de autenticación (401). Las demás rutas permanecen disponibles. Corrija el origen de la SecretRef y, después, recargue o reinicie el Gateway para activar la nueva instantánea. Los valores de SecretRef nunca se resuelven en la ruta pública de solicitudes.

Modelo de seguridad

Cada ruta actúa con la autoridad de TaskFlow de su sessionKey configurada: puede inspeccionar y modificar cualquier TaskFlow que pertenezca a esa sesión. El acceso a TaskFlow siempre pasa por api.runtime.tasks.managedFlows.bindSession(...), por lo que una ruta nunca puede actuar fuera de su sesión vinculada. Para limitar el alcance de los daños:

• Utilice un secreto seguro y único para cada ruta.
• Prefiera una SecretRef a un secreto de texto sin formato insertado directamente.
• Vincule las rutas a la sesión más restringida que sea adecuada para el flujo de trabajo.
• Exponga únicamente la ruta de Webhook específica que necesite.

Orden de procesamiento de solicitudes para cada ruta: comprobaciones del método HTTP (solo POST) y de Content-Type: application/json; después, limitación de frecuencia con ventana fija (120 solicitudes por cada ventana de 60 segundos por clave de ruta+IP del cliente, con hasta 4,096 claves registradas); después, limitación de solicitudes en curso (8 solicitudes simultáneas por clave, con hasta 4,096 claves registradas); después, autenticación mediante secreto compartido; y, por último, lectura de un cuerpo JSON de 256 KB / 15 segundos. Las solicitudes que no superan una comprobación anterior nunca llegan a las posteriores.

Formato de solicitud

Envíe solicitudes POST con Content-Type: application/json y Authorization: Bearer <secret> o 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":"Revisar la cola de entrada"}'

Acciones compatibles

Las acciones de modificación (set_waiting, resume_flow, finish_flow, fail_flow, request_cancel) requieren flowId y expectedRevision para la concurrencia optimista; una revisión obsoleta devuelve 409 revision_conflict.

create_flow

{  "action": "create_flow",  "goal": "Revisar la cola de entrada",  "status": "queued",  "notifyPolicy": "done_only"}

run_task

Valores permitidos de runtime: subagent, acp. startedAt, lastEventAt y progressSummary solo son válidos cuando status es "running"; enviarlos con cualquier otro estado devuelve 400 invalid_request.

{  "action": "run_task",  "flowId": "flow_123",  "runtime": "acp",  "childSessionKey": "agent:main:acp:worker",  "task": "Inspeccionar el siguiente lote de mensajes"}

Estructura de la respuesta

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

{  "ok": false,  "routeId": "zapier",  "code": "not_found",  "error": "No se encontró el TaskFlow.",  "result": {}}

Las vistas de flujos y tareas nunca incluyen metadatos del propietario o de la sesión, por lo que las respuestas no pueden filtrar la sessionKey vinculada a la ruta. Los valores de code incluyen not_found, not_managed, revision_conflict, persist_failed, cancel_requested, cancel_pending, terminal, invalid_request, request_rejected y códigos de reserva específicos de cada acción (mutation_rejected, create_rejected, task_not_created, cancel_rejected) cuando una modificación se rechaza por un motivo que no cubren los códigos con nombre anteriores.

Contenido relacionado

• Hooks: hooks internos basados en eventos frente a este puente de TaskFlow basado en HTTP
• Webhooks del Gateway (configuración de hooks.*): funcionalidad independiente de puntos de conexión HTTP genéricos del Gateway; no es lo mismo que las rutas de este plugin
• SDK de tiempo de ejecución de plugins
• Webhooks de la CLI