Webhooks

El gateway puede exponer un pequeño endpoint HTTP Webhook para disparadores externos.

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
  },
}

Notas:

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'hooks.token'</code>' es requerido cuando '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'hooks.enabled=true'</code>'.

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'hooks.path'</code>' por defecto es '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'/hooks'</code>'.

Cada petición debe incluir el token del hook. Encabezados preferidos:

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'Authorization: Bearer &lt;token&gt;'</code>' (recomendado)

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'x-openclaw-token: &lt;token&gt;'</code>'

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'?token=&lt;token&gt;'</code>' (deprecado; registra advertencia y será eliminado en una versión mayor futura)

#

Payload:

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

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'text'</code>' '<strong>'requerido'</strong>' (string): Descripción del evento (ej., "Nuevo email recibido").

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'mode'</code>' opcional ('<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'now'</code>' | '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'next-heartbeat'</code>'): Si disparar heartbeat inmediatamente (predeterminado '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'now'</code>') o esperar al próximo chequeo periódico.

Efectos:

- Encola un evento del sistema en la sesión <strong>principal</strong>

- Si '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'mode=now'</code>', dispara heartbeat inmediatamente

#

Payload:

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

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'message'</code>' '<strong>'requerido'</strong>' (string): El prompt o mensaje para que el agente procese.

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'name'</code>' opcional (string): Nombre legible del hook (ej., "GitHub"), usado como prefijo en el resumen de sesión.

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'sessionKey'</code>' opcional (string): Clave para identificar la sesión del agente. Por defecto es un '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'hook:&lt;uuid&gt;'</code>' aleatorio. Usar una clave consistente permite conversaciones multi-turno dentro del contexto del hook.

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'wakeMode'</code>' opcional ('<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'now'</code>' | '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'next-heartbeat'</code>'): Si disparar heartbeat inmediatamente (predeterminado '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'now'</code>') o esperar al próximo chequeo periódico.

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'deliver'</code>' opcional (boolean): Si es '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'true'</code>', la respuesta del agente será enviada al canal de mensajería. Por defecto es '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'true'</code>'. Respuestas que son solo reconocimientos de heartbeat serán automáticamente omitidas.

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'channel'</code>' opcional (string): Canal de mensajería para entrega. Uno de: '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'last'</code>', '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'whatsapp'</code>', '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'telegram'</code>', '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'discord'</code>', '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'slack'</code>', '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'mattermost'</code>' (plugin), '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'signal'</code>', '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'imessage'</code>', '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'msteams'</code>'. Por defecto es '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'last'</code>'.

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'to'</code>' opcional (string): Identificador del destinatario para el canal (ej., 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 MS Teams). Por defecto es el último destinatario en la sesión principal.

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'model'</code>' opcional (string): Sobrescribir modelo (ej., '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'anthropic/claude-3-5-sonnet'</code>' o alias). Debe estar en la lista de modelos permitidos si está restringido.

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'thinking'</code>' opcional (string): Sobrescribir nivel de pensamiento (ej., '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'low'</code>', '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'medium'</code>', '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'high'</code>').

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'timeoutSeconds'</code>' opcional (number): Duración máxima para la ejecución del agente en segundos.

Efectos:

- Ejecuta un turno de agente <strong>aislado</strong> (su propia clave de sesión)

- Siempre publica un resumen en la sesión <strong>principal</strong>

- Si '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'wakeMode=now'</code>', dispara heartbeat inmediatamente

#

Los nombres de hook personalizados se resuelven vía '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'hooks.mappings'</code>' (ver configuración). Los mapeos pueden

usar plantillas opcionales o transformar payloads arbitrarios en acciones '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'wake'</code>' o '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'agent'</code>'

ReferenceAutomationWebhookPage.step06.p3

ReferenceAutomationWebhookPage.step06.p4

ReferenceAutomationWebhookPage.step06.p5

ReferenceAutomationWebhookPage.step06.p6

ReferenceAutomationWebhookPage.step06.p7

ReferenceAutomationWebhookPage.step06.p8

ReferenceAutomationWebhookPage.step06.p9

ReferenceAutomationWebhookPage.step06.p10

ReferenceAutomationWebhookPage.step06.p11

ReferenceAutomationWebhookPage.step06.p12

ReferenceAutomationWebhookPage.step06.p13

ReferenceAutomationWebhookPage.step06.p14

ReferenceAutomationWebhookPage.step06.p15

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'200'</code>' for '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'/hooks/wake'</code>'

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'202'</code>' for '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'/hooks/agent'</code>' (async run started)

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'401'</code>' authorization failed

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'400'</code>' invalid payload

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'413'</code>' payload too large

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

#

Add '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'model'</code>' to the agent payload (or mapping) to override the model for that run:

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 aplicas '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'agents.defaults.models'</code>', asegúrate de que incluya el modelo de anulación.

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

- Keep the hook endpoint behind loopback, Tailscale, or a trusted reverse proxy.

- Use a dedicated hook token; don't reuse the gateway auth token.

- Avoid including sensitive raw payloads in Webhook logs.

- By default, hook payloads are treated as untrusted and wrapped in safety boundaries.

Si debes deshabilitar esto para un hook específico, configura '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'allowUnsafeExternalContent: true'</code>'

in that hook's mapping (dangerous).