Tout produit SaaS finit par envoyer des webhooks, et presque chaque première implémentation a les mêmes quatre défauts : le récepteur ne peut pas vérifier qui a envoyé le message, une nouvelle tentative crée une commande en double, un récepteur lent bloque l'émetteur, et personne ne sait si l'événement 4821 a jamais été livré. La spécification Standard Webhooks (version 1.0.2, février 2026), adoptée par des fournisseurs de paiement, de messagerie et d'identité, règle le premier point par convention ; les autres sont des choix de conception des deux côtés. Cet article suit le cycle de vie d'un événement, les en-têtes et la procédure de vérification, le calendrier de nouvelles tentatives qui fonctionne, et les modes de défaillance à tester avant qu'un client ne les trouve.
Un événement, de la file à la livraison
tadata
Deux transitions portent l'essentiel de la conception. Un 4xx est définitif : le récepteur a rejeté le message, et renvoyer les mêmes octets ne le fera pas changer d'avis, sauf 408 et 429 qui veulent dire « plus tard ». Et un événement en lettre morte est rejouable par le client : le tableau de bord qui liste les livraisons échouées et propose un bouton de relecture est la fonction qui transforme un ticket de support en libre-service.
Ce qui passe sur le fil
tadata
La chaîne signée est webhook-id.webhook-timestamp.corps brut. Signer l'horodatage défait le rejeu ; signer les octets bruts impose au récepteur de vérifier avant d'analyser le JSON, parce qu'une resérialisation change les espaces et l'ordre des clés. Stripe, les fournisseurs fondés sur Svix et les bibliothèques de référence de la spécification utilisent tous une tolérance de cinq minutes.
La liste de contrôle du récepteur, dans l'ordre
tadata
Comment espacer les nouvelles tentatives
tadata
Les chiffres exacts comptent moins que trois propriétés : la première nouvelle tentative vient vite (un redémarrage de déploiement dure quelques secondes), les délais grandissent jusqu'à devenir quotidiens, et la gigue étale les tentatives pour que dix mille événements ne frappent pas un point d'entrée convalescent à la même seconde. Stripe réessaie jusqu'à trois jours ; les fournisseurs fondés sur Svix utilisent un calendrier fixe de huit tentatives sur environ un jour ; GitHub ne réessaie pas automatiquement, c'est pourquoi ses clients construisent leur propre relecture. Arrêtez sur un 4xx, et désactivez un point d'entrée qui échoue à chaque livraison depuis des jours, après avoir écrit à son propriétaire.
Pourquoi l'idempotence est l'affaire du récepteur
tadata
La livraison au moins une fois est la seule garantie qu'un émetteur peut honnêtement donner sur HTTP : une réponse perdue après que le récepteur a traité l'événement ressemble exactement à un délai dépassé. Les doublons sont donc normaux, et le récepteur doit rendre inoffensif le traitement du même webhook-id deux fois. La table des reçus indexée par l'id, écrite dans la même transaction que l'effet, est tout le mécanisme ; garder les ids pendant toute la fenêtre de nouvelles tentatives de l'émetteur (trois jours) plutôt que quelques minutes ferme la dernière brèche.
Modes de défaillance à tester avant de livrer
tadata
La ligne sur l'ordre mérite un mot. Les webhooks arrivent dans le désordre sous les nouvelles tentatives, et réordonner côté récepteur est un jeu perdu ; le schéma robuste consiste à traiter le webhook comme une notification qu'une chose a changé et à relire l'état courant de l'objet dans l'API par son id, de sorte qu'un événement périmé ne puisse rien faire régresser.
En résumé
Un webhook est une petite requête HTTP au grand rayon d'action : elle traverse deux organisations, deux cycles de déploiement et deux notions de « livré ». Adoptez les en-têtes Standard Webhooks pour que chaque récepteur puisse utiliser un vérificateur sur étagère, réessayez avec recul et gigue pendant des jours et arrêtez sur un 4xx, rendez le récepteur idempotent avec une table de reçus, et traitez les événements comme des invitations à relire l'état. Puis construisez le tableau de bord, parce que la première question du support sur les webhooks est toujours « l'avez-vous envoyé ? ». Nos articles sur la conception d'API et la modélisation des menaces couvrent l'interface au sens large et ses risques.
Sources : spécification Standard Webhooks v1.0.2 (février 2026) et sa liste de contrôle du récepteur ; documentation de Stripe, Svix et GitHub sur les nouvelles tentatives et les signatures ; missions. Lus le 19 octobre 2026.
Nous utilisons des cookies analytiques pour améliorer votre expérience. Aucune donnée personnelle n'est collectée.