Qu'est-ce qu'un webhook ? Définition, sécurité, retries

Qu'est-ce qu'un webhook ?

Un webhook est une requête HTTP, presque toujours un POST, qu'un service envoie à une URL que vous avez enregistrée quand quelque chose se produit de son côté. Vous donnez votre URL au fournisseur une seule fois. Ensuite il vous appelle avec un petit payload JSON à chaque événement, comme un paiement réussi ou un build terminé. Vous n'avez jamais besoin de demander "y a-t-il du nouveau ?".

Webhooks et polling

Sans webhooks, vous faites du polling : votre code appelle l'API du fournisseur à intervalle régulier pour chercher des changements. Cela a trois coûts.

• Délai. Avec un intervalle de 60 secondes, un événement attend en moyenne 30 secondes avant que vous le remarquiez.
• Gaspillage. La plupart des appels ne renvoient rien de nouveau, mais consomment de la bande passante et comptent dans les limites de débit du fournisseur (voir pourquoi les API limitent le débit, en anglais).
• Compromis. Interroger plus vite fait buter sur les limites, interroger plus lentement fait réagir tard.

Un webhook inverse la logique : celui qui sait que l'événement a eu lieu vous prévient tout de suite.

Comment se déroule la livraison d'un webhook

1. Vous enregistrez une URL HTTPS chez le fournisseur, généralement dans une page de paramètres.
2. Un événement survient : un client paie, une pull request est fusionnée, une sonde échoue.
3. Le fournisseur construit un payload, par exemple {"event": "charge.succeeded", "data": {"id": "ch_123", "amount": 1500}}, et l'envoie en POST à votre URL avec des en-têtes comme le type d'événement, un identifiant de livraison et une signature.
4. Votre endpoint vérifie la requête, enregistre ou met en file l'événement et répond avec un statut 2xx.
5. S'il répond par une erreur ou pas du tout, le fournisseur réessaie plus tard.

Vérifier chaque webhook

Quiconque connaît votre URL peut lui envoyer un POST : un handler non vérifié peut être trompé pour marquer des commandes comme payées ou accorder un accès. La défense habituelle est une signature HMAC : le fournisseur signe le corps exact de la requête avec un secret partagé (HMAC est défini dans la RFC 2104) et envoie le résultat dans un en-tête. Vous le recalculez et rejetez toute différence. Stripe utilise l'en-tête Stripe-Signature et ses bibliothèques rejettent par défaut les horodatages de plus de 5 minutes, ce qui bloque les rejeux.

Deux détails causent la plupart des échecs. D'abord, la vérification de signature exige le corps brut : ne laissez pas votre framework parser puis resérialiser le JSON avant de vérifier. Ensuite, comparez les signatures en temps constant. Un bearer token statique dans un en-tête est plus faible, car une seule requête capturée peut être rejouée. Une liste blanche d'adresses IP aide comme couche supplémentaire, mais se casse quand le fournisseur change d'adresses.

Nouvelles tentatives, doublons et ordre

La livraison est au moins une fois, pas exactement une fois. Stripe réessaie un événement échoué pendant trois jours au plus en mode live, et GitHub attend une réponse 2xx en 10 secondes. Votre handler verra donc des doublons et parfois des événements dans le désordre (Stripe ne garantit pas l'ordre).

• Rendez les handlers idempotents. Stockez l'identifiant de l'événement ou de la livraison et ignorez ceux déjà traités.
• Accusez réception vite, travaillez ensuite. Enregistrez l'événement, renvoyez 200 et traitez-le depuis une file.
• Ne comptez pas sur l'ordre. Si order.fulfilled arrive avant order.created, récupérez l'objet courant via l'API plutôt que de vous fier à la séquence.

Erreurs courantes avec les webhooks

• Sauter la vérification de signature parce que "personne ne connaît l'URL".
• Parser le corps avant de vérifier, si bien que la signature ne correspond jamais.
• Faire un traitement lent dans la requête, ce qui provoque des timeouts puis des nouvelles tentatives en double.
• Renvoyer 200 alors que l'enregistrement de l'événement a échoué : le fournisseur ne réessaie jamais.
• Tester seulement sur localhost. Utilisez un tunnel ou la CLI du fournisseur pour relayer de vrais événements, et rejouez-en un avec curl pour vérifier votre handler.
• Ne jamais consulter le journal de livraison du fournisseur : les échecs passent inaperçus.

Les webhooks dans le monitoring

Les webhooks sont le moyen par lequel les sondes transmettent une alerte à vos propres outils. Dans le monitoring d'API LoadFocus, un canal d'alerte webhook envoie un POST HTTP avec un corps JSON vers une URL HTTPS que vous contrôlez quand un check échoue, se rétablit, fonctionne en mode dégradé ou qu'un certificat SSL est sur le point d'expirer. Le payload contient des champs comme event (par exemple check.failed), le nom et l'URL du check, le statut, la localisation et un horodatage. Votre endpoint doit renvoyer rapidement un 2xx. L'enregistrement du canal envoie un POST de confirmation unique, et la configuration est décrite dans la documentation du canal d'alerte webhook (en anglais). Gardez l'URL réceptrice difficile à deviner et vérifiez les champs du payload avant d'agir. Pour le contexte général, voir le monitoring d'API.

Questions fréquentes : webhooks

Un webhook est-il la même chose qu'une URL de callback ?

Oui. Webhook, callback HTTP et reverse API décrivent le même schéma : un service appelle une URL que vous lui avez donnée quand un événement se produit.

Quelle est la différence entre webhooks et WebSockets ?

Un webhook est une requête HTTP ponctuelle envoyée par un fournisseur quand un événement survient. Un WebSocket est une connexion bidirectionnelle durable entre un client et un serveur. Utilisez les webhooks pour des événements occasionnels entre services et les WebSockets pour un trafic bidirectionnel constant, comme un chat.

Que se passe-t-il si mon endpoint est indisponible ?

La plupart des fournisseurs réessaient un moment puis abandonnent. Stripe, par exemple, réessaie pendant trois jours au plus en mode live. Ensuite, c'est à vous de rejouer les événements : surveillez donc le journal de livraison du fournisseur et gardez un moyen de récupérer à nouveau les événements manqués.

Comment tester un handler de webhook en local ?

Les fournisseurs n'atteignent pas localhost : exposez-le via un tunnel comme ngrok ou utilisez la CLI du fournisseur pour relayer les événements, comme le fait la CLI Stripe. Rejouez ensuite des payloads enregistrés avec curl pendant le débogage.

Webhooks ou polling ?

Webhooks quand la latence compte ou que les événements sont rares. Polling pour les synchronisations en masse ou quand vous ne pouvez pas exposer d'endpoint HTTPS public. Beaucoup d'intégrations combinent les deux : webhooks pour la rapidité, un polling occasionnel pour rattraper ce qui a été manqué.