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

Plugins

Plugin de Webhooks

El Plugin Webhooks agrega rutas HTTP autenticadas que vinculan la automatización externa con los TaskFlows de OpenClaw.

Úsalo cuando quieras que un sistema de confianza, como Zapier, n8n, un trabajo de CI o un servicio interno, cree y dirija TaskFlows gestionados sin escribir primero un plugin personalizado.

Dónde se ejecuta

El Plugin Webhooks se ejecuta dentro del proceso Gateway.

Si tu Gateway se ejecuta en otra máquina, instala y configura el plugin en ese host de Gateway y luego reinicia el Gateway.

Configurar rutas

Define 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: "Zapier TaskFlow bridge",
            },
          },
        },
      },
    },
  },
}

Campos de ruta:

  • enabled: opcional, el valor predeterminado es true
  • path: opcional, el valor predeterminado es /plugins/webhooks/<routeId>
  • sessionKey: sesión obligatoria propietaria de los TaskFlows vinculados
  • secret: secreto compartido o SecretRef obligatorio
  • controllerId: id de controlador opcional para los flujos gestionados creados
  • description: nota opcional para el operador

Entradas secret compatibles:

  • Cadena de texto sin formato
  • SecretRef con source: "env" | "file" | "exec"

Si una ruta respaldada por un secreto no puede resolver su secreto al iniciar, el plugin omite esa ruta y registra una advertencia en lugar de exponer un endpoint dañado.

Modelo de seguridad

Cada ruta es de confianza para actuar con la autoridad de TaskFlow de su sessionKey configurada.

Esto significa que la ruta puede inspeccionar y mutar TaskFlows propiedad de esa sesión, por lo que deberías:

  • Usar un secreto único y robusto por ruta
  • Preferir referencias a secretos en lugar de secretos en texto claro en línea
  • Vincular rutas a la sesión más restringida que se ajuste al flujo de trabajo
  • Exponer solo la ruta de webhook específica que necesitas

El plugin aplica:

  • Autenticación mediante secreto compartido
  • Guardas de tamaño del cuerpo de la solicitud y de tiempo de espera
  • Limitación de tasa de ventana fija
  • Limitación de solicitudes en curso
  • Acceso a TaskFlow vinculado al propietario mediante api.runtime.tasks.managedFlows.bindSession(...)

Formato de solicitud

Envía solicitudes POST con:

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

Ejemplo:

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

Acciones compatibles

Actualmente, el plugin acepta estos valores JSON de action:

  • 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

Crea un TaskFlow gestionado para la sesión vinculada de la ruta.

Ejemplo:

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

run_task

Crea una tarea secundaria gestionada dentro de un TaskFlow gestionado existente.

Los runtimes permitidos son:

  • subagent
  • acp

Ejemplo:

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

Forma de la respuesta

Las respuestas correctas devuelven:

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

Las solicitudes rechazadas devuelven:

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

El plugin elimina intencionalmente los metadatos de propietario/sesión de las respuestas de webhook.

Documentación relacionada