Comment configurer les alertes webhook signées depuis un outil de monitoring

Les alertes webhook sont le liant d'intégration qui connecte un moniteur de temps d'activité à tout le reste : PagerDuty, Opsgenie, systèmes d'incident internes, suivi des tickets, bots Slack personnalisés. La mécanique de base est simple (votre moniteur envoie du JSON à votre point de terminaison lorsqu'un incident se déclenche). Les détails (vérification de la signature, comportement des tentatives, idempotence) sont où l'implémentation devient intéressante. Ce guide couvre la configuration pratique.

Pourquoi les webhooks plutôt que les e-mails ou Slack

Les e-mails et Slack fonctionnent bien pour les humains. Les webhooks fonctionnent pour les systèmes. Trois cas d'usage justifient la configuration supplémentaire.

Routage vers un outil de pagination qui gère votre rotation d'astreinte (PagerDuty, Opsgenie). Conduite d'un système interne de gestion des incidents qui ouvre des tickets, crée des threads Slack, et exécute automatiquement des runbooks. Déclenchement de la remédiation automatisée (redémarrer un worker, augmenter la capacité d'un cluster, basculer vers une région de secours). Les trois nécessitent une charge utile structurée, une livraison sûre pour les tentatives, et l'authentification. Les webhooks fournissent tous trois ; les e-mails et Slack n'en fournissent aucun.

La structure de charge utile à attendre

La plupart des outils de monitoring envoient une charge utile JSON similaire lors d'événements d'incident. Les noms de champs exacts varient, mais quatre sections sont standard.

• event : 'monitor.down' ou 'monitor.up', de sorte que votre point de terminaison puisse router les ouvertures et fermetures.
• monitor : id, nom, type, cible, dernier statut. Assez de contexte pour identifier ce qui est cassé.
• check : code de statut, temps de réponse, message d'erreur. Le détail de diagnostic.
• timestamp : ISO 8601, UTC. Important pour le tri et la déduplémentation.

Vérification de la signature HMAC

Tout point de terminaison webhook exposé à Internet public a besoin de vérification de signature. Sans elle, un attaquant qui devine votre URL peut simuler un événement « monitor down » et déclencher votre remédiation, votre pagination, et votre réponse support. Avec la vérification HMAC, seul votre outil de monitoring peut signer des charges valides.

Le modèle : l'outil de monitoring envoie un en-tête X-Monitorah-Signature avec le HMAC-SHA256 du corps de la requête brut, clé avec un secret partagé. Votre point de terminaison recalcule le HMAC du corps en utilisant le même secret, compare (en temps constant) à la valeur d'en-tête, rejette en cas de non-concordance. Utilisez les octets bruts du corps pour le HMAC, pas le JSON analysé : une seule différence d'espace blanc produit une signature différente.

Tentatives et idempotence

La livraison des webhooks est au mieux possible, non garantie. Deux modèles rendent votre endpoint robuste face aux nouvelles tentatives et aux défaillances partielles.

• Respectez les nouvelles tentatives avec élégance. La plupart des moniteurs réessayeront une réponse 5xx avec une augmentation exponentielle pendant jusqu'à 24 heures. Retournez un 5xx si vous ne pouvez pas traiter l'événement; retournez un 2xx si vous pouvez.
• Traitez l'ID d'événement comme une clé d'idempotence. Le même incident ouvert peut déclencher le webhook deux fois lors d'une perturbation réseau. Dédupliquez en stockant l'ID d'événement et en ignorant si vous l'avez déjà traité.
• Répondez rapidement. Prenez moins de 5 secondes pour retourner un 2xx, même si votre traitement en aval prend plus de temps. Utilisez une file d'attente de tâches si nécessaire.

Intégration avec PagerDuty

PagerDuty accepte un webhook générique via son API Events v2. Le flux : votre outil de monitoring POST une charge JSON personnalisée vers votre gestionnaire. Votre gestionnaire vérifie le HMAC, mappe la charge dans le schéma attendu par PagerDuty, et POST vers le point de terminaison des événements de PagerDuty avec votre clé de routage.

La couche de traduction est le bon endroit pour ajouter la déduplication, les règles d'escalade et les clés de routage par moniteur. L'interface utilisateur de PagerDuty gère la rotation une fois l'événement ingéré. Gardez le traducteur simple. La version la plus propre fait moins de cent lignes de code.

Un gestionnaire webhook de démarrage en 20 lignes

Le modèle : recevoir POST, extraire l'en-tête X-Monitorah-Signature, HMAC-SHA256 le corps brut avec votre secret partagé, comparer en temps constant avec l'en-tête. S'ils correspondent, analyser JSON, dédupliquer par ID d'événement, dispatcher. S'ils ne correspondent pas, retourner 401 sans traitement. Ce gestionnaire est le bloc de construction pour chaque intégration en haut : PagerDuty, Opsgenie, bots Slack, systèmes d'incidents internes. Une fois en place, chaque nouvelle intégration est quelques lignes de logique de dispatcher et rien de plus.