---
read_when:
    - Quieres activar o controlar TaskFlows desde un sistema externo
    - Estás configurando el Plugin de webhooks incluido
summary: 'Plugin de Webhooks: entrada autenticada de TaskFlow para automatización externa de confianza'
title: Plugin de Webhooks
x-i18n:
    generated_at: "2026-05-06T17:59:38Z"
    model: gpt-5.5
    provider: openai
    source_hash: 9d21d96f680fa24d4a53c1ed5759f800d3cfdc3336789c42c15266edd8ce9e80
    source_path: plugins/webhooks.md
    workflow: 16
---

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`:

```json5
{
  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:

```bash
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:

```json
{
  "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:

```json
{
  "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:

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

Las solicitudes rechazadas devuelven:

```json
{
  "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

- [SDK de runtime de Plugin](/es/plugins/sdk-runtime)
- [Descripción general de hooks y webhooks](/es/automation/hooks)
- [Webhooks de CLI](/es/cli/webhooks)