Cómo configurar alertas de webhook firmadas desde una herramienta de monitorización

Las alertas de webhook son el pegamento de integración que conecta un monitor de uptime con todo lo demás: PagerDuty, Opsgenie, sistemas internos de incidentes, gestores de tickets, bots personalizados de Slack. La mecánica básica es sencilla (tu monitor envía un POST con JSON a tu endpoint cuando se activa un incidente). Los detalles (verificación de firma, comportamiento de reintentos, idempotencia) son donde la implementación se vuelve interesante. Esta guía cubre la configuración práctica.

Por qué webhooks en lugar de correo electrónico o Slack

El correo electrónico y Slack funcionan bien para personas. Los webhooks funcionan para sistemas. Tres casos de uso justifican la configuración adicional.

Enrutar a una herramienta de paging que gestiona tu rotación de guardia (PagerDuty, Opsgenie). Impulsar un sistema interno de gestión de incidentes que abre tickets, crea hilos de Slack y ejecuta runbooks automáticamente. Activar la remediación automatizada (reiniciar un worker, escalar un clúster, hacer failover a una región de respaldo). Los tres necesitan una carga útil estructurada, entrega segura ante reintentos y autenticación. Los webhooks proporcionan los tres; el correo electrónico y Slack no proporcionan ninguno.

La forma de la carga útil que se debe esperar

La mayoría de las herramientas de monitorización envían una carga útil JSON similar en los eventos de incidente. Los nombres exactos de los campos varían, pero cuatro secciones son estándar.

• event: «monitor.down» o «monitor.up», para que tu endpoint pueda enrutar aperturas y cierres.
• monitor: id, nombre, tipo, destino, último estado. Suficiente contexto para identificar qué está roto.
• check: código de estado, tiempo de respuesta, mensaje de error. El detalle de diagnóstico.
• timestamp: ISO 8601, UTC. Importante para el orden y la deduplicación.

Verificación de la firma HMAC

Cualquier endpoint de webhook expuesto a la internet pública necesita verificación de firma. Sin ella, un atacante que adivine tu URL puede falsificar un evento de «monitor caído» y activar tu remediación, tu paging y tu respuesta de soporte. Con la verificación HMAC, solo tu herramienta de monitorización puede firmar cargas útiles válidas.

El patrón: la herramienta de monitorización envía una cabecera X-Monitorah-Signature con el HMAC-SHA256 del cuerpo bruto de la solicitud, firmado con un secreto compartido. Tu endpoint recalcula el HMAC del cuerpo usando el mismo secreto, lo compara (en tiempo constante) con el valor de la cabecera y rechaza la solicitud si no coincide. Usa los bytes brutos del cuerpo para el HMAC, no el JSON analizado: una sola diferencia de espacio en blanco produce una firma distinta.

Reintentos e idempotencia

La entrega de webhooks es de mejor esfuerzo, no garantizada. Dos patrones hacen que tu endpoint sea robusto frente a reintentos y fallos parciales.

• Gestiona los reintentos con elegancia. La mayoría de los monitores reintentarán una respuesta 5xx con backoff exponencial durante hasta 24 horas. Devuelve un 5xx si no puedes procesar el evento; devuelve un 2xx si puedes.
• Trata el id del evento como una clave de idempotencia. La misma apertura de incidente puede disparar el webhook dos veces durante un fallo de red. Deduplica almacenando el id del evento y omitiéndolo si ya lo has procesado.
• Responde con rapidez. Tarda menos de 5 segundos en devolver un 2xx, incluso si tu procesamiento posterior lleva más tiempo. Usa una cola de trabajos si es necesario.

Integración con PagerDuty

PagerDuty acepta un webhook genérico a través de su Events API v2. El flujo: tu herramienta de monitorización envía un POST con una carga útil JSON personalizada a tu propio handler. Tu handler verifica el HMAC, mapea la carga útil al esquema esperado por PagerDuty y envía un POST al endpoint de eventos de PagerDuty con tu routing key.

La capa de traducción es el lugar adecuado para añadir deduplicación, reglas de escalado y routing keys por monitor. La interfaz de PagerDuty gestiona la rotación una vez que el evento ha sido ingerido. Mantén el traductor sencillo. La versión más limpia tiene menos de cien líneas de código.

Un handler de webhook inicial en 20 líneas

El patrón: recibir POST, extraer la cabecera X-Monitorah-Signature, aplicar HMAC-SHA256 al cuerpo bruto con tu secreto compartido y comparar en tiempo constante con la cabecera. Si coinciden, analizar el JSON, deduplicar por id de evento y despachar. Si no coinciden, devolver 401 sin procesar. Este handler es el bloque de construcción para cada integración posterior: PagerDuty, Opsgenie, bots de Slack, sistemas internos de incidentes. Una vez que está implementado, cada nueva integración son unas pocas líneas de lógica de despacho y nada más.