Alertas por webhook: payload, cabeceras y reintentos

Además del correo electrónico y la campana de notificaciones de la aplicación, Pingsured puede enviar una alerta como solicitud HTTP a la URL que usted elija: su herramienta de gestión de incidencias, una integración de chat, una plataforma de automatización o su propio endpoint. Los webhooks están disponibles a partir del plan Team y los configura un propietario o un administrador de la cuenta, para un ping concreto o como opción predeterminada para todos los pings de la cuenta.

La solicitud

Cada alerta es un POST con un cuerpo JSON:

la URL debe usar https;
Content-Type: application/json;
User-Agent: Pingsured-Alarm/1;
se siguen hasta 3 redirecciones;
su endpoint dispone de 10 segundos para responder con un estado 2xx.

Se rechazan las direcciones de redes privadas, de loopback o link-local, incluso cuando un nombre público se resuelve en una de ellas o una redirección apunta a una de ellas.

El payload

Campo	Significado
`event`	`alarm.fired`, o `alarm.fired.test` para el botón de prueba
`version`	la versión del payload, actualmente `1`
`account_id`	la cuenta a la que pertenece el ping
`task_id`	el ID del ping
`task_name`	el nombre del ping tal como aparece en la aplicación
`channel`	siempre `webhook`
`trigger`	la regla que se ha disparado, como `first_error` o `first_ok`
`result.status`	el estado actual del ping: `ok`, `warning`, `error` o `unknown`
`result.prev_status`	el estado anterior a este cambio, si lo había
`result.started_at`	cuándo se ejecutó la comprobación que produjo este resultado, en ISO 8601 UTC
`result.location`	la ubicación cuyas comprobaciones dispararon la alerta, por ejemplo `de` o `us-west`

Una alerta típica cuando un sitio web deja de responder:

event: alarm.fired
trigger: first_error
result.status: error, result.prev_status: ok

y cuando se recupera, lo mismo con trigger first_ok y los estados a la inversa.

Cabeceras para enrutar y deduplicar

X-Pingsured-Event repite el nombre del evento, para que pueda enrutar sin analizar el cuerpo.
X-Pingsured-Event-Version repite la versión del payload.
X-Pingsured-Delivery identifica la entrega. No cambia cuando una entrega se reintenta, así que guárdelo e ignore una segunda solicitud con un ID que ya haya procesado.

Reintentos

Si su endpoint no responde a tiempo, no es accesible o responde 408, 425, 429 o cualquier estado 5xx, la entrega se vuelve a intentar: cinco intentos en total, separados por 30 segundos, 5 minutos, 30 minutos y 2 horas. Cualquier otra respuesta 4xx se considera definitiva y no se reintenta, como tampoco una URL que se rechaza antes del envío (http sin cifrar, una dirección privada, demasiadas redirecciones).

Cuándo se envían los webhooks

Un webhook sigue las mismas reglas que cualquier otro canal de alertas:

Qué cambios. La configuración recomendada avisa en el primer fallo y en la recuperación. También puede recibir una alerta por cada resultado fallido.
Cuántos fallos antes. Un umbral como «3 de las últimas 5 comprobaciones» evita que una sola respuesta lenta haga saltar una alerta. Los umbrales de alarma y de recuperación se configuran por separado.
Con qué frecuencia. Las alertas repetidas para el mismo ping y el mismo canal se retienen durante 15 minutos; un cambio de estado se envía siempre de inmediato.
Desde dónde. Cada ubicación desde la que se comprueba un ping se evalúa por separado, y un fallo en cualquiera de ellas es una alerta para el ping.

Todavía no disponible

Las solicitudes no están firmadas. Mientras tanto, utilice una URL con una ruta o un token difícil de adivinar, y trate X-Pingsured-Delivery como un identificador, no como prueba de origen.
Una URL de webhook por ping, más una predeterminada para toda la cuenta.