--- title: Integración Webhook - Guía completa de disparadores HTTP sidebarTitle: Webhooks description: "Integra webhooks de Echobell en tus apps y servicios: métodos HTTP, variables, plantillas, cabeceras y ejemplos prácticos para notificaciones instantáneas." --- # Integración Webhook 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. **¿Usabas claves Direct?** Las claves Direct ahora son canales. Cada una de tus claves se convirtió en un canal con el mismo nombre, y su antigua URL `https://hook.echobell.one/d/…` sigue funcionando exactamente igual que antes, así que tus scripts no necesitan cambios. Las nuevas integraciones pueden usar la URL webhook `/t/` del canal que aparece en la app, que acepta los mismos campos. En la URL `/t/`, `notificationType` solo puede bajar el nivel con el que te suscribiste (consulta [Nivel de notificación](#nivel-de-notificación)), así que si un script pide `calling`, suscríbete al canal como Llamada. ## 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](#plantillas-personalizadas) 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. | Campo | Descripción | |---|---| | `title` | Título de la notificación. Por defecto, el nombre del canal. | | `body` | Cuerpo de la notificación. Vacío por defecto. | | `externalLink` | Un enlace que se muestra con el registro de la notificación. Útil para apuntar a un panel, un log o un pull request. | | `notificationType` | `active`, `time-sensitive` o `calling`. Solo puede bajar el nivel que eligió cada suscriptor — consulta [Nivel de notificación](#nivel-de-notificación). | ### Petición GET ```http GET https://hook.echobell.one/t/?title=Backup%20finished&body=Nightly%20backup%20completed ``` ### Petición POST Envía un cuerpo JSON: ```http POST https://hook.echobell.one/t/ 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`: ```bash curl -d "title=Hello&body=World" https://hook.echobell.one/t/ ``` ### 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: ```json { "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: ```json { "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](/es/docs/notification) 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: ```bash curl -d "title=Deploy finished&body=v2.1.0 is live¬ificationType=active" \ https://hook.echobell.one/t/ ``` 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: ```http GET https://hook.echobell.one/t/?server_name=Produccion&cpu_usage=95 ``` O en un cuerpo JSON: ```http POST https://hook.echobell.one/t/ 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](/es/docs/template) para ver la sintaxis completa y [Condiciones](/es/docs/conditions) 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. ```http POST https://hook.echobell.one/t/ 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](/es/docs/conditions) 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](#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](/es/docs/support) o contáctanos en echobell@weelone.com.