Retour au blog Guide Pratique - 8 min

Comment configurer un webhook d’incident vers votre outil d’équipe

Un webhook d’incident envoie un POST signé à Slack ou à votre outil. Vérifiez la signature, dédoublonnez, et répondez 2xx vite.

Un webhook d’incident est une URL de votre côté qui reçoit un POST quand une surveillance change d’état : échec confirmé, ou retour au vert. Slack, Mattermost, un outil de tickets ou un script interne peuvent être cette URL. Le POST doit être signé, reconnu une seule fois, et acquitté tout de suite par un 2xx. Sans cela, vous avez soit des alertes forgées, soit des doublons, soit une file de renvois qui noie le canal.

Ce que le message doit contenir

Le corps, en JSON, gagne à porter au minimum :

ChampUsage
event_idIdentifiant unique, pour ignorer un renvoi
statusdown ou up (ou les mots de votre outil)
urlL’URL contrôlée, pas seulement le nom du site
checked_atHeure du contrôle, en UTC, avec fuseau explicite
http_code0 si timeout, sinon le code reçu
detailTimeout, certificat, marqueur de contenu absent

Un message sans URL oblige l’astreinte à ouvrir un autre outil pour savoir laquelle des vingt pages est tombée. L’heure sans fuseau se décale d’une ou deux heures selon la saison et le poste. Restez en UTC dans le JSON, et convertissez à l’affichage.

Le format exact dépend de l’émetteur. Webhooks d’alerte décrit le branchement côté surveillance. Côté réception, tenez-vous au contrat écrit : si un champ manque, répondez 400 une fois, ne bouclez pas.

Recevoir sans vous faire piéger

  1. URL en HTTPS, chemin non devinable. Ce n’est pas une protection suffisante : ajoutez un secret.
  2. Calculez la signature HMAC du corps brut (pas du JSON ré-encodé) avec le secret, comparez avec hash_equals à l’en-tête prévu (X-Signature ou celui documenté par l’émetteur).
  3. Rejetez un horodatage trop vieux (par exemple plus de cinq minutes) si l’émetteur en signe un : cela limite le rejeu d’un POST intercepté.
  4. Si event_id est déjà en base, répondez 200 et ne recréez pas de ticket.
  5. Répondez 204 ou 200 dès la signature vérifiée et l’enregistrement fait. Envoyez la notification Slack dans la foulée seulement si c’est rapide. Sinon, mettez l’événement en file et acquittez quand même.
  6. En cas de signature fausse : 401, sans détail. Ne traitez pas le corps.

Un timeout de votre endpoint est lu comme un échec. L’émetteur renvoie. Si chaque renvoi ouvre un message Slack, une panne de dix minutes devient quarante messages. L’identifiant d’événement est là pour ça.

Pour un canal d’équipe déjà en place, le cas Slack est décrit dans Alertes Slack. Le webhook ne remplace pas la consigne : qui est d’astreinte, au bout de combien de minutes on appelle. Cette consigne est dans Procédure d’alerte de l’équipe.

Tester avant la première vraie panne

Déclenchez un échec volontaire sur une URL de test (mauvais mot-clé de contenu, ou hôte de préproduction), pas sur le paiement un vendredi. Vérifiez trois choses : le message arrive, un second POST identique ne duplique pas le ticket, et le retour au vert envoie un message distinct up que l’on ne confond pas avec un nouvel incident.

Gardez l’e-mail en secours si le webhook répond 500. SiteGarde peut notifier les deux. Testez le secours en coupant volontairement l’URL du webhook : l’alerte e-mail doit encore partir. Un canal unique non testé est une alerte que vous découvrirez muette le jour où l’origine est vraiment en panne.

Ne journalisez pas le secret ni le corps complet s’il contient un jeton. Le statut, l’URL et l’event_id suffisent dans vos logs. Tournez le secret si l’URL a fuité, et mettez à jour l’émetteur en même temps : une signature vérifiée avec l’ancien secret refusera tous les POST, y compris les vrais.


Signature sur le corps brut, event_id pour les renvois, 2xx immédiat. Le test se fait sur une URL de recette, avant d’en avoir besoin.

Questions fréquentes

À quoi sert un webhook d’incident ?

À recevoir un POST dès qu’un contrôle passe en échec ou revient au vert, dans l’outil où l’équipe travaille déjà. L’e-mail reste un canal de secours. Le webhook évite de copier l’alerte à la main.

Pourquoi vérifier une signature ?

N’importe qui peut envoyer un POST à une URL publique. Une signature HMAC calculée avec un secret partagé prouve que l’appel vient de votre outil de surveillance. Sans secret, l’URL du webhook est un bouton d’alerte ouvert.

Que répondre au webhook ?

Un code 2xx dès que vous avez accepté le corps, puis traitez en file si le travail est long. Un 500 ou un timeout provoque des renvois. Répondez vite, et ignorez un second POST déjà traité grâce à un identifiant d’événement.

Surveiller mes URL