Integración Webhook - Guía completa de disparadores HTTP

Los webhooks son la forma más versátil de activar notificaciones de Echobell. Esta guía completa cubre todo lo que necesitas saber sobre la integración de alertas basadas en webhook en tus sistemas, desde conceptos básicos hasta patrones de uso avanzados.

Qué es un webhook

Un webhook es una forma en que una aplicación proporciona información en tiempo real a otras aplicaciones. Es como un número de teléfono que das a alguien - cuando llaman a ese número, tu teléfono suena. En el mundo digital, cuando algo sucede en un sistema, envía una petición HTTP a una URL (el webhook) que proporcionaste, activando una acción en tu sistema.

Por ejemplo, cuando el uso de CPU de tu servidor es demasiado alto, tu sistema de monitoreo puede llamar a la URL webhook de Echobell, que luego activa una notificación para alertarte. Esto sucede automáticamente y en tiempo real, sin que tengas que comprobar constantemente el uso de CPU por ti mismo.

Resumen

Los canales son la forma en que Echobell recibe webhooks. Cada canal tiene su propia URL webhook y, cuando se llama a esa URL, el canal envía una notificación a todos sus suscriptores.

Crear un canal solo requiere un nombre. Por defecto, el canal muestra el title, el body y el externalLink que envía cada petición, tal cual se envían — útil para tus propios scripts, tareas cron y pasos de CI. Cuando la petición viene de otro servicio, puedes activar una plantilla personalizada y construir la notificación a partir de los datos de la petición.

Formato de URL Webhook

https://hook.echobell.one/t/{token-del-canal}

Puedes encontrar la URL webhook de tu canal en la vista de detalles del canal en la aplicación Echobell.

Realizando peticiones Webhook

Por defecto, un canal lee cuatro campos de cada petición. Los nombres de campo no distinguen mayúsculas de minúsculas (title, Title y TITLE son el mismo campo), y pueden ir en la cadena de consulta de un GET, o en un cuerpo POST JSON o codificado como formulario.

Petición GET

GET https://hook.echobell.one/t/<channel-token>?title=Backup%20finished&body=Nightly%20backup%20completed

Petición POST

Envía un cuerpo JSON:

POST https://hook.echobell.one/t/<channel-token>
Content-Type: application/json

{
  "title": "CPU alert",
  "body": "Production CPU usage reached 95%",
  "externalLink": "https://dashboard.example.com/alerts/123"
}

O un cuerpo codificado como formulario, que es lo que envía curl -d:

curl -d "title=Hello&body=World" https://hook.echobell.one/t/<channel-token>

Abrir la URL en un navegador

Un GET sin cadena de consulta y sin cuerpo — lo que envía un navegador o la vista previa de enlaces de una app de chat — no notifica a nadie. En su lugar, el canal responde con una breve descripción de los campos que acepta:

{
  "success": true,
  "notificationTriggered": false,
  "message": "This is an Echobell channel webhook. It pushes a notification to the channel's subscribers. Send a title or a body to trigger one.",
  "usage": { "...": "..." }
}

Añade un title o un body para enviar una notificación. Un POST siempre notifica, incluso con el cuerpo vacío (el título es entonces el nombre del canal).

Solo POST

Cada canal tiene un interruptor Solo POST en Configuraciones avanzadas de la app de Echobell. Está desactivado por defecto.

Cuando está activado, solo POST puede activar el canal. Una petición GET a la URL del webhook se rechaza con 405 Method Not Allowed y no se envía ninguna notificación:

{
  "success": false,
  "notificationTriggered": false,
  "message": "This trigger only accepts POST requests; GET triggering is disabled in its settings."
}

Las peticiones HEAD no se ven afectadas: responden 200 y nunca activan una notificación, esté Solo POST activado o no.

Actívalo cuando la URL del webhook acabe en un sitio que carga enlaces automáticamente — un mensaje de chat, una página de wiki, la barra de direcciones del navegador — para que previsualizar o abrir la URL no pueda disparar una alerta. Déjalo desactivado si alguno de tus clientes activa el canal con GET.

Nivel de notificación

Cada persona que se suscribe a un canal elige para él un tipo de notificación en la app: Normal (active), Urgente o Llamada. Esa elección es el nivel más alto con el que el canal puede avisarle. Una petición puede enviar notificationType para pedir un nivel más bajo, nunca uno más alto.

Por ejemplo, suscríbete a tu canal "Production" como Llamada. Las peticiones de caídas omiten notificationType, así que suenan como una llamada telefónica. Los eventos rutinarios, como un despliegue terminado, envían notificationType=active y llegan como una notificación normal:

curl -d "title=Deploy finished&body=v2.1.0 is live&notificationType=active" \
  https://hook.echobell.one/t/<channel-token>

Un compañero que se suscribió al mismo canal como Urgente recibe la caída como una notificación urgente, nunca como una llamada.

Los canales con Plantilla personalizada activada ignoran notificationType en la petición: cada suscriptor siempre recibe el nivel que eligió.

Plantillas personalizadas

Por defecto, un canal muestra el title, el body y el externalLink que envía cada petición. Cuando la petición viene de un servicio cuyo payload no puedes cambiar — una herramienta de monitoreo, un sistema de CI, una tienda —, activa Plantilla personalizada en Configuraciones avanzadas dentro de los ajustes del canal y escribe una plantilla de título y una plantilla de cuerpo. El canal construye entonces cada notificación a partir de esas plantillas, y cada parámetro de consulta y campo JSON de la petición se convierte en una variable.

Pasa variables a través de parámetros de consulta:

GET https://hook.echobell.one/t/<channel-token>?server_name=Produccion&cpu_usage=95

O en un cuerpo JSON:

POST https://hook.echobell.one/t/<channel-token>
Content-Type: application/json

{
  "server_name": "Produccion",
  "cpu_usage": 95
}

Variables de plantilla

Usa las variables en tus plantillas de notificación con la sintaxis {{nombreVariable}}:

Título: Alerta del servidor {{server_name}}
Cuerpo: El uso de CPU ha alcanzado {{cpu_usage}}%

Cuando se activa, estas plantillas se completarán con los valores proporcionados en tu petición webhook. Consulta Plantillas para ver la sintaxis completa y Condiciones para filtrar qué peticiones notifican.

Variables especiales

• externalLink: Cuando se incluye en la petición, esto crea un enlace clickeable en la vista de registros de notificación, a menos que el canal tenga su propia plantilla de enlace externo.

POST https://hook.echobell.one/t/<channel-token>
Content-Type: application/json

{
  "server_name": "Produccion",
  "cpu_usage": 95,
  "externalLink": "https://dashboard.example.com/alerts/123"
}

Variables de tiempo del sistema (UTC)

Además de los datos que envías, Echobell proporciona variables de tiempo del sistema de solo lectura que siempre están disponibles en plantillas y condiciones (UTC). Los campos planos incluyen date, time, year, month, dayOfWeek, hour, minute y second. Otros —como sys.dayOfWeekName, sys.epochMs y sys.epochSeconds— solo están disponibles bajo el espacio de nombres sys.. Consulta Condiciones para la lista completa y ejemplos.

Casos de uso comunes

Los webhooks son particularmente útiles para:

• Monitoreo y alertas de servidor
• Notificaciones de pipeline CI/CD
• Actualizaciones de estado de dispositivos IoT
• Seguimiento de errores de aplicación
• Notificaciones de pedidos de comercio electrónico
• Alertas de sistema automatizadas

Mejores prácticas

1. Manejo de errores: Echobell responde a cada llamada webhook con un estado HTTP y un cuerpo JSON. Revisa primero el estado HTTP y después notificationTriggered para saber si se envió una notificación:
   • 200 OK: la petición se procesó. notificationTriggered: true significa que se envió una notificación. notificationTriggered: false significa que no se envió nada a propósito: las condiciones del canal no se cumplieron (conditionsMet: false), o un GET vacío recibió la descripción de uso.
   • 400 Bad Request: el token de la URL tiene una longitud incorrecta.
   • 404 Not Found: ningún canal tiene este token (code: "TRIGGER_TOKEN_NOT_FOUND"; en una URL /d/ antigua, DIRECT_KEY_NOT_FOUND). El canal se eliminó o su URL de webhook se restableció.
   • 405 Method Not Allowed: Solo POST está activado y la petición no era un POST.
   • 413 Payload Too Large: el cuerpo de la petición supera 1 MiB.
   • 429 Too Many Requests: más de 120 peticiones en un minuto a la misma URL de webhook. La respuesta incluye una cabecera Retry-After (en segundos); espera ese tiempo antes de reintentar.
   • 500: problema temporal del servidor, reintenta con retroceso exponencial.
2. Límite de tasa: Implementa retrasos razonables entre llamadas webhook para evitar sobrecargar tu sistema de notificaciones. Cada URL de webhook acepta hasta 120 peticiones por minuto; por encima de eso, Echobell responde 429.
3. Seguridad de datos: Solo comparte URLs webhook con sistemas y servicios confiables
4. Pruebas: Prueba tu integración webhook con datos mínimos antes de implementar en producción

Privacidad y seguridad

Recuerda que:

• Las URLs webhook deben tratarse como secretos
• Solo envía datos necesarios en peticiones webhook
• Todo el contenido de notificación se almacena localmente en los dispositivos de los suscriptores
• Nuestros servidores solo procesan la petición webhook y enrutan notificaciones

Solución de problemas

Si tus webhooks no funcionan como se espera:

1. Verifica que la URL webhook sea correcta
2. Comprueba si el canal está activo
3. Asegúrate de que tu payload JSON esté correctamente formateado (para peticiones POST)
4. Confirma que todas las variables requeridas en tus plantillas están siendo proporcionadas (canales con plantilla personalizada)
5. Comprueba si el canal tiene suscriptores activos

¿Necesitas ayuda? Visita nuestro Centro de soporte o contáctanos en echobell@weelone.com.