Un webhook d’alerte prévient votre outil (messagerie d’équipe, ticket, script) qu’une URL surveillée a changé d’état. L’outil de monitoring envoie une requête HTTP vers une adresse que vous exposez. Vous n’allez pas chercher l’information : elle arrive au moment du changement. L’e-mail reste utile pour une boîte lue par des humains. Le webhook sert quand un système doit ouvrir un canal, créer un ticket, ou taire un doublon.
Le corps minimal
Un JSON court suffit. Les champs qui permettent d’agir sans rappeler l’API :
url: la page contrôlée ;state: échec ou retour à la normale ;http_code: le code reçu, ou nul si la connexion n’a pas abouti ;error: dns, tls, timeout, contenu, quand il n’y a pas de code utile ;checked_at: heure UTC du contrôle qui a fait basculer l’état ;incident_id: le même identifiant pour l’échec et pour le retour.
N’envoyez pas le HTML de la page dans le webhook. Il peut contenir des données de formulaire ou un jeton affiché par erreur. Le détail se consulte dans l’outil de monitoring, derrière une session.
Déclenchez l’envoi au changement d’état seulement, après la règle d’échecs consécutifs décrite dans les seuils d’alerte. Un POST à chaque essai, y compris les succès, transforme le webhook en copie bruyante de l’historique.
Réponse, reprises, signature
Votre URL doit répondre un code 2xx dès que le corps est accepté et mis en file, pas après le traitement long. L’émetteur considère qu’un délai dépassé ou un code 5xx est un échec d’envoi, et il réessaie. Si vous créez le ticket avant de répondre, un réessai en crée un second. Répondez d’abord, traitez ensuite, et dédupliquez avec incident_id plus state.
Les reprises doivent être espacées. Une rafale immédiate de dix essais aggrave une panne de votre récepteur. Côté émetteur, un plafond d’essais évite de poster encore le lendemain un incident déjà clos à la main.
Servez le récepteur en HTTPS uniquement. Faites vérifier une signature : un secret partagé, connu de l’émetteur et du récepteur, sert à calculer un HMAC du corps brut. Le récepteur recalcule et compare. Sans cela, n’importe qui peut poster un faux « site rétabli » s’il devine l’adresse. Ne mettez pas le secret dans l’URL : il finirait dans les journaux d’accès. Placez-le dans un en-tête.
Refusez les corps qui ne correspondent pas au contrat, et journalisez le refus sans journaliser le secret. Un webhook qui accepte tout finit par ouvrir des tickets sur des essais de scanners. Limitez aussi le débit côté récepteur : une rafale de changements d’état, le jour d’un incident général, ne doit pas saturer la file de tickets au point de perdre l’ouverture du premier.
E-mail et webhook ensemble
Gardez l’e-mail comme filet pour les personnes, et le webhook pour l’outil. Les deux partent du même changement d’état, sinon l’un dit « incident » et l’autre reste silencieux. Documentez qui acquitte : si le ticket et l’e-mail demandent chacun une réponse, l’incident est traité deux fois.
Le week-end, le webhook n’a de valeur que si le système en aval réveille vraiment quelqu’un. Un canal d’équipe archivé le vendredi soir est un e-mail de plus. Le guide des incidents le week-end porte sur cette chaîne humaine.
SiteGarde a sa place comme émetteur du POST, pas comme récepteur de vos autres outils. Testez avec un incident volontaire sur une URL prévue pour ça, et vérifiez trois choses : un seul ticket à l’ouverture, un message de retour à la normale avec le même identifiant, et aucun ticket si la signature est fausse.