Webhooks

Objetivo

Conecta tus agents a servicios externos por HTTP. El módulo Webhooks tiene dos pestañas:

• Outbound — acciones que tus agents invocan (POST a un CRM, consultar un pedido, crear un ticket).
• Inbound — endpoints que sistemas externos llaman para disparar un agent (desde n8n, Make, Zapier o cualquier API REST).

Acceso

Sidebar -> Webhooks Ruta: /app/{tenant}/webhooks

Roles

• solo owner, admin.
• El rol agent ve el elemento en el sidebar pero recibe un banner "Access denied": solo owners y admins pueden gestionar webhooks.

Requisitos previos

• Un email verificado (requerido para crear un webhook).
• La cantidad de webhooks está limitada por tu plan.

Webhooks salientes (Outbound)

Los webhooks salientes son acciones que un agent puede invocar durante una conversación. Pulsa Create Webhook.

Endpoint

Autenticación

• None
• Bearer token
• Basic (usuario + contraseña)
• API Key (valor + nombre del parámetro, por defecto X-API-Key, enviado como header o query)
• OAuth 2.0 (client credentials): token URL, client id, client secret, scope, y dónde van las credenciales (body o basic)

Las credenciales se cifran. Al editar un webhook, deja un campo de secreto en blanco para conservar el valor actual.

Opciones de la petición

• Sign outbound requests: añade una firma HMAC. Genera y copia el secreto de firma (se muestra una vez).
• Timeout: un deslizador de 1 a 30 segundos.
• Headers y Query Params: filas clave/valor.
• Parameters: un constructor visual (Name / Type: string, number, integer, boolean / Description / Required), con opción de cambiar a un editor JSON. Son los valores que el agent aporta al momento de llamar.
• Body Template: filas clave/valor o JSON, con un selector de body encoding (JSON o form).
• Response handling: un Response path para extraer un campo de la respuesta JSON, y Success codes que cuentan como éxito.

Los marcadores {variable} pueden aparecer en la URL, headers, query params y body; el agent los completa cuando llama al webhook.

Probar

• Dentro del modal, completa valores de ejemplo para cada {placeholder} y ejecuta una prueba — verás el estado HTTP, la duración y el cuerpo de la respuesta.
• Cada tarjeta de webhook guardado tiene un botón Test (deshabilitado con un tooltip cuando la URL aún contiene {variables}).
• Las ejecuciones recientes aparecen como logs (método, estado, duración, respuesta o error, y hora).

Webhooks entrantes (Inbound)

Los webhooks entrantes permiten que un sistema externo dispare un agent haciendo POST a un endpoint por agent en {origin}/api/inbound/{token}. Cambia a la pestaña Inbound y pulsa New inbound webhook.

Después de crear o regenerar un endpoint, un panel de una sola vez muestra la URL del endpoint, el secreto en texto plano (solo una vez) y un snippet curl listo para ejecutar. Copia el secreto ahora — no se vuelve a mostrar.

Cada tarjeta de endpoint entrante tiene un interruptor active/paused, Regenerate secret, Edit y Delete, un indicador de última activación, y un log expandible Recent events (estado: success, auth_failed, rate_limited, inactive, error; IP de origen; extracto del payload). Los endpoints entrantes están limitados por tu plan.

Buenas prácticas

• Dale a los webhooks salientes un Name y Description claros para que el agent sepa exactamente cuándo llamarlos.
• Usa el flujo de prueba antes de depender de un webhook en producción.
• Prefiere auth HMAC o Bearer para los endpoints entrantes; evita None.
• Cuida los secretos: se muestran solo una vez. Regenera si un secreto se filtra.