Configura Webhooks en OpenClaw: Guía de integración rápida

¿Alguna vez has sentido que integrar disparadores externos con tu flujo de trabajo es más complicado de lo que debería? Configurar sistemas que reaccionen a eventos en tiempo real suele implicar lidiar con configuraciones pesadas o procesos de polling que consumen recursos innecesarios.

Los Webhooks en Gateway te permiten conectar eventos externos de forma directa y sin complicaciones. Con esta funcionalidad, puedes exponer un endpoint HTTP pequeño para que herramientas de terceros activen acciones específicas en tu sistema de manera inmediata.

Webhooks

Gateway puede exponer un endpoint de webhook HTTP pequeño para disparadores externos.

Habilitar

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    // Optional: restrict explicit `agentId` routing to this allowlist.
    // Omit or include "*" to allow any agent.
    // Set [] to deny all explicit `agentId` routing.
    allowedAgentIds: ["hooks", "main"],
  },
}

Notas:

hooks.token es obligatorio cuando hooks.enabled=true.
hooks.path tiene el valor por defecto /hooks.

Autenticación

Cada solicitud debe incluir el token del hook. Es mejor usar headers:

Authorization: Bearer <token> (recomendado)
x-openclaw-token: <token>
Los tokens en query-string se rechazan (?token=... devuelve 400).
Trata a quienes tengan el hooks.token como llamadores de total confianza para la superficie de entrada del hook en ese Gateway. El contenido del payload del hook sigue considerándose no confiable, pero esto no es un límite de autenticación separado para no propietarios.

Endpoints

`POST /hooks/wake`

Payload:

{ "text": "System line", "mode": "now" }

text obligatorio (string): La descripción del evento (por ejemplo, “Nuevo correo recibido”).
mode opcional (now | next-heartbeat): Indica si se debe activar un heartbeat inmediato (por defecto now) o esperar a la siguiente revisión periódica.

Efecto:

Encola un evento de sistema para la sesión main.
Si mode=now, activa un heartbeat inmediato.

`POST /hooks/agent`

Payload:

{
  "message": "Run this",
  "name": "Email",
  "agentId": "hooks",
  "sessionKey": "hook:email:msg-123",
  "wakeMode": "now",
  "deliver": true,
  "channel": "last",
  "to": "+15551234567",
  "model": "openai/gpt-5.2-mini",
  "thinking": "low",
  "timeoutSeconds": 120
}

message obligatorio (string): El prompt o mensaje que el agente debe procesar.
name opcional (string): Nombre legible para el hook (por ejemplo, “GitHub”), usado como prefijo en los resúmenes de sesión.
agentId opcional (string): Dirige este hook a un agente específico. Los IDs desconocidos usan al agente por defecto. Cuando se configura, el hook se ejecuta usando el workspace y la configuración del agente resuelto.
sessionKey opcional (string): La clave usada para identificar la sesión del agente. Por defecto, este campo se rechaza a menos que hooks.allowRequestSessionKey=true.
wakeMode opcional (now | next-heartbeat): Indica si se debe activar un heartbeat inmediato (por defecto now) o esperar a la siguiente revisión periódica.
deliver opcional (boolean): Si es true, la respuesta del agente se enviará al canal de mensajería. Por defecto es true. Las respuestas que son solo confirmaciones de heartbeat se omiten automáticamente.
channel opcional (string): El canal de mensajería para la entrega. Usa last o cualquier canal configurado o ID de plugin, por ejemplo discord, matrix, telegram o whatsapp. Por defecto es last.
to opcional (string): El identificador del destinatario para el canal (por ejemplo, número de teléfono para WhatsApp/Signal, ID de chat para Telegram, ID de canal para Discord/Slack/Mattermost (plugin), ID de conversación para Microsoft Teams). Por defecto es el último destinatario en la sesión principal.
model opcional (string): Sobrescribe el modelo (por ejemplo, anthropic/claude-sonnet-4-6 o un alias). Debe estar en la lista de modelos permitidos si existen restricciones.
thinking opcional (string): Sobrescribe el nivel de pensamiento (por ejemplo, low, medium, high).
timeoutSeconds opcional (number): Duración máxima para la ejecución del agente en segundos.

Efecto:

Ejecuta un turno de agente aislado (con su propia clave de sesión).
Siempre publica un resumen en la sesión main.
Si wakeMode=now, activa un heartbeat inmediato.

Política de clave de sesión (cambio importante)

Las sobrescrituras de sessionKey en el payload de /hooks/agent están desactivadas por defecto.

Recomendado: configura un hooks.defaultSessionKey fijo y mantén desactivadas las sobrescrituras en las solicitudes.
Opcional: permite sobrescrituras en las solicitudes solo cuando sea necesario y restringe los prefijos.

Configuración recomendada:

{
  hooks: {
    enabled: true,
    token: "${OPENCLAW_HOOKS_TOKEN}",
    defaultSessionKey: "hook:ingress",
    allowRequestSessionKey: false,
    allowedSessionKeyPrefixes: ["hook:"],
  },
}

Configuración de compatibilidad (comportamiento heredado):

{
  hooks: {
    enabled: true,
    token: "${OPENCLAW_HOOKS_TOKEN}",
    allowRequestSessionKey: true,
    allowedSessionKeyPrefixes: ["hook:"], // strongly recommended
  },
}

`POST /hooks/<name>` (mapeado)

Los nombres de hooks personalizados se resuelven mediante hooks.mappings (ver configuración). Un mapeo puede convertir payloads arbitrarios en acciones wake o agent, con plantillas opcionales o transformaciones de código.

Opciones de mapeo (resumen):

hooks.presets: ["gmail"] habilita el mapeo integrado de Gmail.
hooks.mappings te permite definir match, action y plantillas en la configuración.
hooks.transformsDir + transform.module carga un módulo JS/TS para lógica personalizada.
- hooks.transformsDir (si se configura) debe permanecer dentro de la raíz de transformaciones bajo tu directorio de configuración de OpenClaw (normalmente ~/.openclaw/hooks/transforms).
- transform.module debe resolverse dentro del directorio de transformaciones efectivo (se rechazan rutas de escape o salto de directorios).
Usa match.source para mantener un endpoint de entrada genérico (enrutamiento basado en el payload).
Las transformaciones en TS requieren un cargador de TS (como bun o tsx) o archivos .js precompilados en tiempo de ejecución.
Configura deliver: true + channel/to en los mapeos para dirigir las respuestas a una interfaz de chat (channel por defecto es last y recurre a WhatsApp).
agentId dirige el hook a un agente específico; los IDs desconocidos usan al agente por defecto.
hooks.allowedAgentIds restringe el enrutamiento explícito de agentId. Omítelo (o incluye *) para permitir cualquier agente. Usa [] para denegar el enrutamiento explícito de agentId.
hooks.defaultSessionKey establece la sesión por defecto para las ejecuciones de agentes vía hook cuando no se proporciona una clave explícita.
hooks.allowRequestSessionKey controla si los payloads de /hooks/agent pueden configurar sessionKey (por defecto: false).
hooks.allowedSessionKeyPrefixes restringe opcionalmente los valores explícitos de sessionKey de los payloads de solicitud y mapeos.
allowUnsafeExternalContent: true desactiva el envoltorio de seguridad de contenido externo para ese hook (peligroso; solo para fuentes internas de confianza).
openclaw webhooks gmail setup escribe la configuración hooks.gmail para openclaw webhooks gmail run. Consulta Gmail Pub/Sub para ver el flujo completo de monitoreo de Gmail.

Respuestas

200 para /hooks/wake
200 para /hooks/agent (ejecución asíncrona aceptada)
401 en caso de fallo de autenticación
429 tras fallos repetidos de autenticación desde el mismo cliente (revisa Retry-After)
400 si el payload no es válido
413 si el payload excede el tamaño permitido

Ejemplos

curl -X POST http://127.0.0.1:18789/hooks/wake \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"text":"New email received","mode":"now"}'

curl -X POST http://127.0.0.1:18789/hooks/agent \
  -H 'x-openclaw-token: SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"message":"Summarize inbox","name":"Email","wakeMode":"next-heartbeat"}'

Usar un modelo diferente

Añade model al payload del agente (o al mapeo) para sobrescribir el modelo en esa ejecución:

curl -X POST http://127.0.0.1:18789/hooks/agent \
  -H 'x-openclaw-token: SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.2-mini"}'

Si obligas a usar agents.defaults.models, asegúrate de que el modelo de sobrescritura esté incluido en esa lista.

curl -X POST http://127.0.0.1:18789/hooks/gmail \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"source":"gmail","messages":[{"from":"Ada","subject":"Hello","snippet":"Hi"}]}'

Seguridad

Mantén los endpoints de los hooks detrás de loopback, tailnet o un reverse proxy de confianza.
Usa un token dedicado para los hooks; no reutilices los tokens de autenticación del Gateway.
Es preferible usar un agente dedicado para hooks con un tools.profile estricto y sandboxing para que la entrada de hooks tenga un radio de impacto limitado.
Los fallos repetidos de autenticación tienen un límite de tasa por dirección de cliente para frenar intentos de fuerza bruta.
Si usas enrutamiento multi-agente, configura hooks.allowedAgentIds para limitar la selección explícita de agentId.
Mantén hooks.allowRequestSessionKey=false a menos que necesites sesiones seleccionadas por el llamador.
Si habilitas sessionKey en las solicitudes, restringe hooks.allowedSessionKeyPrefixes (por ejemplo, ["hook:"]).
Evita incluir payloads crudos sensibles en los logs de los webhooks.
Los payloads de los hooks se tratan como no confiables y se envuelven con límites de seguridad por defecto.
Si debes desactivar esto para un hook específico, configura allowUnsafeExternalContent: true en el mapeo de ese hook (esto es peligroso).

AI Setup Assistant

Pasos siguientes

OpenClaw Expert

Sigues atascado?

Si esta pagina no resolvio tu caso, pregunta a OpenClaw Expert para pasos concretos.