Webhooks

El canal webhook es un adaptador HTTP genérico de entrada/salida. Ejecuta su propio servidor HTTP embebido en un puerto que elijas, acepta mensajes con formato JSON, los entrega al agente y (opcionalmente) envía mediante POST las respuestas del agente a una URL que especifiques. Úsalo como el adaptador universal para cualquier sistema que pueda producir un HTTP POST.

No es lo mismo que el endpoint /webhook del gateway. El servicio del gateway tiene su propio POST /webhook para clientes emparejados que acceden al agente a través de HTTP, que se encuentra bajo [gateway] y se describe en Operaciones → Despliegue de red. Esta página documenta únicamente el canal [channels.webhook].

Configuración

zeroclaw config set channels.webhook.<alias>.auth_header    # entrada enmascarada, almacenada cifrada

export ZEROCLAW_channels__webhook__<alias>__auth_header=

zeroclaw config set channels.webhook.<alias>.excluded_tools <value>

export ZEROCLAW_channels__webhook__<alias>__excluded_tools=

zeroclaw config set channels.webhook.<alias>.listen_path <value>

export ZEROCLAW_channels__webhook__<alias>__listen_path=

zeroclaw config set channels.webhook.<alias>.max_retries <value>

export ZEROCLAW_channels__webhook__<alias>__max_retries=

zeroclaw config set channels.webhook.<alias>.port <value>

export ZEROCLAW_channels__webhook__<alias>__port=

zeroclaw config set channels.webhook.<alias>.reply_min_interval_secs <value>

export ZEROCLAW_channels__webhook__<alias>__reply_min_interval_secs=

zeroclaw config set channels.webhook.<alias>.reply_queue_depth_max <value>

export ZEROCLAW_channels__webhook__<alias>__reply_queue_depth_max=

zeroclaw config set channels.webhook.<alias>.retry_base_delay_ms <value>

export ZEROCLAW_channels__webhook__<alias>__retry_base_delay_ms=

zeroclaw config set channels.webhook.<alias>.retry_max_delay_ms <value>

export ZEROCLAW_channels__webhook__<alias>__retry_max_delay_ms=

zeroclaw config set channels.webhook.<alias>.secret    # entrada enmascarada, almacenada cifrada

export ZEROCLAW_channels__webhook__<alias>__secret=

zeroclaw config set channels.webhook.<alias>.send_method <value>

export ZEROCLAW_channels__webhook__<alias>__send_method=

zeroclaw config set channels.webhook.<alias>.send_url <value>

export ZEROCLAW_channels__webhook__<alias>__send_url=

Referencia completa de campos: referencia de configuración.

Entrante

El canal vincula 0.0.0.0:{port} y enruta POST {listen_path}.

Cuerpo de la solicitud (JSON):

{
  "sender": alice,
  "contenido": "Hola, agente.",
  "thread_id": optional-conversation-id
}

• sender: requerido, se usa como la identidad del remitente del mensaje.
• content: requerido, el mensaje del usuario que se entrega al agente. Un contenido vacío devuelve 400.
• thread_id: opcional. Si se establece, la respuesta del agente se dirige al mismo hilo; de lo contrario, las respuestas se dirigen a sender.

El éxito devuelve 200 OK. Un JSON mal formado o un content vacío devuelve 400. La contrapresión (cola de canal llena) devuelve 503.

Verificación de firma

Cuando secret está configurado, cada solicitud entrante debe incluir un encabezado X-Webhook-Signature:

X-Webhook-Signature: sha256=<hex-encoded HMAC-SHA256 of the raw body>

El canal calcula HMAC-SHA256(secret, raw_body), lo codifica en hexadecimal y lo compara con el valor del encabezado (el prefijo sha256= se elimina antes de la decodificación). Si no coincide o falta el encabezado, se devuelve 401.

Cuando secret no está definido, el canal se niega a iniciarse (el listener se detiene al arrancar con un error que indica al operador que configure uno). Un canal de webhook habilitado siempre requiere un secret configurado. Esto es un fallo rápido deliberado: un listener de webhook sin autenticación con acceso al agente es una entrada abierta que no debería existir en ningún despliegue.

Cambio incompatible. Los despliegues que antes ejecutaban el listener sin secreto detrás de un proxy inverso o lo vinculaban a una red privada ahora deben configurar un secret en [channels.webhook.<alias>].secret. Se elimina la ruta de reserva sin secreto: un listener de webhook habilitado se trata como un riesgo incondicional al que no debería exponerse ninguna topología de despliegue. Los operadores en esta situación deben establecer un secret y mantener el listener detrás de su proxy inverso existente o seguir vinculándolo a una red privada; cualquiera de las dos opciones es válida, el secreto es lo que ahora resulta esencial.

Saliente

Cuando se establece send_url, cada respuesta del agente se entrega como una solicitud HTTP a esa URL:

{send_method} {send_url}
Authorization: {auth_header}    # solo si auth_header está configurado
Content-Type: application/json

{
  "content": "texto de respuesta del agente",
  "thread_id": "id de hilo opcional",
  "recipient": "id de destinatario opcional"
}

• send_method es POST (predeterminado) o PUT. Cualquier otro valor recurre a POST.
• auth_header se envía textualmente como el valor del encabezado Authorization; incluya el esquema usted mismo (p. ej., Bearer xyz, Basic dXNlcjpwYXNz).
• recipient se omite cuando está vacío.
• Las respuestas que no sean 2xx generan un error en los registros; la respuesta del agente se considera fallida.

Cuando send_url no está configurado, las respuestas del agente se descartan silenciosamente (registradas en nivel debug). Esta es la configuración correcta para flujos entrantes de tipo “fire-and-forget” donde la respuesta se entrega a través de otro canal.

Exposición pública

El canal se vincula directamente a 0.0.0.0. Para exponerlo en internet público:

1. Proxy inverso: termina TLS en nginx / Caddy / Traefik y haz proxy al puerto del canal. Consulta Operaciones → Despliegue de red.
2. Tunnel: configura [tunnel] (ngrok, cloudflare o tailscale) y el daemon levanta el túnel junto con el canal.
3. Solo local: ejecútelo dentro de una red privada y haga que su productor acceda directamente a la dirección LAN/loopback.

Empareja siempre la exposición pública con secret. Un receptor de webhook sin autenticación es una entrada abierta al agente.

Reintentos de salida

Cuando send_url está configurado, la entrega saliente reintenta los fallos transitorios, errores de red, HTTP 429 y HTTP 5xx, con retroceso exponencial (jitter de ±25%) limitado por retry_max_delay_ms. Las respuestas 4xx que no sean 429 fallan inmediatamente sin reintentar. Cuando el servidor devuelve un encabezado Retry-After en 429 o 503, ese valor se respeta y también se limita mediante retry_max_delay_ms. Configurar max_retries = 0 significa enviar y olvidar (fire-and-forget).

Ver también

• Operaciones → Despliegue en red: terminación TLS, túneles, el /webhook independiente del gateway
• Canal → Descripción general