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

La cabecera de la página incluye un chip Docs que enlaza de vuelta a esta documentación.

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

• Los webhooks salientes cuentan contra el límite de webhooks de tu plan; los endpoints entrantes tienen un límite propio que cuenta solo los endpoints activos (pausar uno libera un cupo). Alcanzar cualquiera de los dos abre un diálogo de mejora de plan.
• Los webhooks entrantes necesitan al menos un agent — el botón de crear está deshabilitado hasta que tengas uno.

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 Auth (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 (OAuth 2.0 sigue exigiendo la token URL y el client id).

Opciones de la petición

• Sign outbound requests: Helios añade a cada petición un header X-Helios-Signature (sha256= + hex, un HMAC-SHA256 del cuerpo de la petición) y un header X-Helios-Timestamp (segundos Unix), para que tu endpoint pueda verificar que de verdad vino de Helios. Pulsa Generate para crear el secreto de firma y cópialo — se muestra una sola vez. Al editar, déjalo en blanco para conservar el secreto guardado.
• Timeout: un deslizador de 1 a 30 segundos (por defecto 15).
• Headers y Query Parameters: 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 codificación del cuerpo (JSON o Form URL-encoded).
• Response handling: un Response field (ruta con puntos, p. ej. data.items) para entregarle al agent solo esa parte de la respuesta JSON, y Extra success codes — códigos de estado además de 2xx que se tratan como éxito, para que por ejemplo un 404 se lea como resultado vacío y no como error.

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 pulsa Send Test — verás el estado HTTP, la duración y el cuerpo de la respuesta. Los parámetros obligatorios se validan igual que en producción, así que un valor de ejemplo faltante hace fallar la prueba en vez de pasar en silencio.
• Cada tarjeta de webhook guardado tiene un botón Test (deshabilitado con un tooltip cuando la URL aún contiene {variables}). Prueba el webhook tal como está guardado: las credenciales cifradas se usan en el servidor y nunca se envían a tu navegador. El panel de resultado muestra el estado, la duración y el cuerpo de la respuesta.

Webhooks entrantes (Inbound)

Los webhooks entrantes permiten que un sistema externo dispare un agent haciendo POST a un endpoint dedicado en {origin}/api/inbound/{token}. Cambia a la pestaña Inbound — muestra cuántos endpoints activos tienes contra el límite de tu plan — 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 ejemplo curl listo para ejecutar según el tipo de autenticación elegido. Copia el secreto ahora — no se vuelve a mostrar.

Autenticar tus peticiones

• HMAC signature (lo más seguro): firma el cuerpo crudo de la petición con el secreto usando HMAC-SHA256 y envía el resultado como X-Signature: sha256= + hex.
• Bearer token: envía el secreto como Authorization: Bearer ....
• Opcionalmente incluye un header X-Timestamp (segundos Unix): cuando está presente, las peticiones fuera de una ventana de 5 minutos se rechazan, lo que protege contra peticiones repetidas.
• None: cualquiera que tenga la URL puede disparar el agent — solo para pruebas rápidas.

Comportamiento del endpoint

• Solo POST, cuerpo JSON de hasta 64 KB.
• Con límite de tasa: 30 peticiones por minuto por endpoint, más una barrera adicional por IP.
• El endpoint responde de inmediato con un acuse; la ejecución del agent y la entrega ocurren en segundo plano, así que el timeout de tu emisor nunca compite con el agent.
• Los endpoints pausados rechazan las peticiones (el intento se registra igualmente como Inactive).

Gestionar endpoints

Cada tarjeta de endpoint entrante tiene un interruptor Active/Paused, Regenerate secret (visible cuando la autenticación no es None), Edit y Delete (con confirmación), un indicador de última activación, la URL del endpoint con un botón Copy, y un log expandible Recent events — las últimas peticiones con estado (Success, Auth failed, Rate limited, Inactive, Error), hora, IP de origen y un extracto del payload.

El límite del plan cuenta los endpoints activos: pausar uno libera un cupo, y reactivarlo vuelve a comprobar el límite.

Buenas prácticas

• Escribe la Description para el agent, no para ti: di cuándo y por qué llamar al webhook. Es lo único que le enseña al agent a usarlo.
• 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.
• Usa Extra success codes para APIs donde un estado no-2xx es una respuesta normal (p. ej. 404 = no encontrado, no un fallo).

Errores comunes

• Access denied: tu rol es agent — solo owners y admins pueden gestionar webhooks.
• No puedo guardar el webhook: Name, Description y una URL válida son obligatorios. La descripción debe ser una frase real (al menos 10 caracteres), no un relleno.
• URL rechazada: solo se permiten URLs http(s) públicas — se bloquean direcciones privadas/internas, trucos con IPs y URLs con credenciales incrustadas. Pon las credenciales en la sección de autenticación.
• Botón Test deshabilitado en la tarjeta: la URL aún contiene {variables}. Abre el webhook con Edit y prueba desde dentro del modal con valores de ejemplo.
• Límite de plan alcanzado: estás en el límite de webhooks o de endpoints entrantes de tu plan. Elimina uno (o, en inbound, pausa uno), o mejora tu plan.
• Los eventos entrantes muestran Auth failed: la firma o el token no coinciden con el secreto del endpoint. Revisa cómo firmas el cuerpo; si perdiste el secreto, usa Regenerate secret y actualiza tu emisor.
• Los eventos entrantes muestran Rate limited: tu emisor superó las 30 peticiones por minuto en ese endpoint. Añade reintentos con espera.
• Los eventos entrantes muestran Inactive: el endpoint está pausado. Vuelve a poner el interruptor en Active.
• WhatsApp o Email no aparecen en Deliver via: el agent elegido no tiene un número de WhatsApp conectado, o su herramienta de envío de email está apagada. Usa el enlace del formulario para configurarlo, o elige otro agent o "No delivery (tools only)".

Relacionado

• Agents
• Integrations
• Scheduled Tasks
• Billing & Usage