Alertes webhook : payload, en-têtes et nouvelles tentatives

En plus de l’e-mail et de la cloche de notification dans l’application, Pingsured peut envoyer une alerte sous forme de requête HTTP vers une URL de votre choix — votre outil de gestion d’incidents, une intégration de messagerie, une plateforme d’automatisation ou votre propre point de terminaison. Les webhooks sont disponibles à partir de l’offre Team. Ils sont configurés par un propriétaire ou un gestionnaire du compte, pour un seul ping ou comme valeur par défaut pour tous les pings du compte.

La requête

Chaque alerte est un POST avec un corps JSON :

l’URL doit utiliser https ;
Content-Type: application/json ;
User-Agent: Pingsured-Alarm/1 ;
jusqu’à 3 redirections sont suivies ;
votre point de terminaison dispose de 10 secondes pour répondre avec un statut 2xx.

Les adresses situées dans des réseaux privés, de bouclage (loopback) ou link-local sont refusées, y compris lorsqu’un nom public se résout vers l’une d’elles ou qu’une redirection y mène.

La charge utile (payload)

Champ	Signification
`event`	`alarm.fired`, ou `alarm.fired.test` pour le bouton de test
`version`	la version de la charge utile, actuellement `1`
`account_id`	le compte auquel appartient le ping
`task_id`	l’identifiant du ping
`task_name`	le nom du ping tel qu’il apparaît dans l’application
`channel`	toujours `webhook`
`trigger`	la règle qui s’est déclenchée, par exemple `first_error` ou `first_ok`
`result.status`	le statut actuel du ping : `ok`, `warning`, `error` ou `unknown`
`result.prev_status`	le statut avant ce changement, s’il y en avait un
`result.started_at`	le moment où s’est exécutée la vérification qui a produit ce résultat, en ISO 8601 UTC
`result.location`	l’emplacement dont les vérifications ont déclenché l’alerte, par exemple `de` ou `us-west`

Une alerte typique lorsqu’un site cesse de répondre :

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

et, lorsqu’il est rétabli, la même alerte avec trigger à first_ok et les statuts inversés.

En-têtes pour le routage et le dédoublonnage

X-Pingsured-Event reprend le nom de l’événement, pour router sans analyser le corps.
X-Pingsured-Event-Version reprend la version de la charge utile.
X-Pingsured-Delivery identifie l’envoi. Il reste identique lorsqu’un envoi est retenté : conservez-le et ignorez une seconde requête portant un identifiant que vous avez déjà traité.

Nouvelles tentatives

Lorsque votre point de terminaison ne répond pas à temps, est injoignable, ou répond 408, 425, 429 ou n’importe quel statut 5xx, l’envoi est retenté — cinq tentatives au total, espacées de 30 secondes, 5 minutes, 30 minutes et 2 heures. Toute autre réponse 4xx est considérée comme définitive et n’est pas retentée, pas plus qu’une URL refusée avant l’envoi (http simple, adresse privée, trop de redirections).

Quand les webhooks sont envoyés

Un webhook suit les mêmes règles que tous les autres canaux d’alerte :

Quels changements. La configuration recommandée envoie une alerte au premier échec et au rétablissement. Vous pouvez aussi être alerté à chaque résultat en échec.
Combien d’échecs d’abord. Un seuil comme « 3 vérifications en échec sur les 5 dernières » évite qu’une seule réponse lente ne réveille quelqu’un. Les seuils d’alarme et de rétablissement se règlent séparément.
À quelle fréquence. Les alertes répétées pour le même ping et le même canal sont retenues pendant 15 minutes ; un changement de statut est toujours envoyé immédiatement.
D’où. Chaque emplacement depuis lequel un ping est vérifié est évalué séparément, et un échec sur n’importe lequel d’entre eux déclenche une alerte pour le ping.

Pas encore disponible

Les requêtes ne sont pas signées. En attendant qu’elles le soient, utilisez une URL avec un chemin ou un jeton difficile à deviner, et considérez X-Pingsured-Delivery comme un identifiant, et non comme une preuve d’origine.
Une seule URL de webhook par ping, plus une URL par défaut pour tout le compte.