Garanties de livraison des webhooks expliquées

Les garanties de livraison des webhooks décrivent à quelle fréquence et dans quel ordre un fournisseur livre les événements à votre point d’accès. La plupart promettent au mieux une livraison au moins une fois. Votre point d’accès reçoit la plupart des événements, parfois deux fois, parfois en retard, parfois dans le désordre. Les intégrations fiables placent les garde-fous côté réception.

Ce guide explique chaque garantie en termes simples, montre ce que promet la documentation de vrais fournisseurs et se termine par une checklist valable pour toute intégration de webhooks, événements de paiement crypto compris.

En bref

• Au moins une fois est le plafond réaliste. Les fournisseurs réessaient jusqu’à ce que vous renvoyiez une réponse 2xx : les doublons sont normaux et vous devez les gérer.
• L’ordre n’est pas garanti. Un événement précoce en dépassement de délai peut arriver après un événement plus tardif : triez donc selon l’horodatage ou le champ de séquence propre à l’événement.
• Acquittez d’abord, traitez ensuite. Vérifiez la signature, stockez l’événement durablement, renvoyez 2xx, puis faites le gros du travail en asynchrone.
• Dédupliquez sur l’identifiant d’événement. Enregistrez-le avec un index unique avant tout effet de bord, comme créditer un solde.
• Traitez les webhooks comme des notifications, pas comme un registre. Réconciliez les enregistrements critiques avec l’API à intervalle régulier pour attraper ce que les nouvelles tentatives ont manqué.
• Chaingateway ne relance pas automatiquement les notifications échouées. Il les liste et les renvoie sur demande.

Que signifient les trois garanties de livraison ?

La sémantique de livraison vient des systèmes distribués, et elle s’applique bien aux webhooks.

Garantie	Ce que fait l’émetteur	Ce qui peut mal tourner	Ce que vous construisez
Au plus une fois	Envoie l’événement une fois et ne réessaie jamais	L’événement est perdu si votre point d’accès est hors service	Réconciliation avec l’API
Au moins une fois	Réessaie jusqu’à votre acquittement ou à épuisement des tentatives	Doublons, arrivées tardives, réordonnancement	Gestionnaire idempotent, déduplication
Exactement une fois	Livrerait une fois, sans perte ni doublon	Impossible à obtenir à travers une frontière réseau non fiable	Au moins une fois plus déduplication

Avec au plus une fois, une tentative échouée signifie un événement perdu. C’est simple pour l’émetteur et risqué dès que de l’argent est en jeu.

Avec au moins une fois, l’émetteur continue d’essayer jusqu’à voir une réponse de succès ou à épuiser son budget de tentatives. La perte devient rare, mais il y a un piège. Imaginons que votre gestionnaire crédite un compte, puis plante avant de renvoyer 200. L’émetteur n’a jamais vu l’acquittement : il renvoie donc l’événement. Du côté de l’émetteur, c’est un comportement correct. Du vôtre, c’est un double crédit, sauf si vous l’empêchez.

Exactement une fois est ce que tout le monde veut et que personne ne peut promettre sur HTTP. L’émetteur ne peut pas savoir si votre serveur a traité la requête quand la connexion tombe. Le substitut pratique est une livraison au moins une fois combinée à un récepteur qui ignore les répétitions. Cette combinaison donne des effets exactement une fois, et c’est ce qui compte vraiment.

Que promettent réellement les fournisseurs ?

Lisez la section sur la livraison dans la documentation de n’importe quel fournisseur de webhooks sérieux, et le même schéma apparaît.

Adobe I/O Events indique que chaque événement est livré au moins une fois par enregistrement, que des doublons peuvent être envoyés et que l’ordre des événements n’est pas garanti. Column, une API bancaire américaine, indique que les événements de webhook ne sont pas garantis d’arriver dans l’ordre de création. Un événement précoce en dépassement de délai peut arriver après un événement plus tardif, car chaque nouvelle tentative est replanifiée indépendamment.

Ce dernier détail explique la plupart des bugs d’ordre. L’événement A échoue une fois et sa nouvelle tentative est planifiée dans une minute. L’événement B, créé après, réussit tout de suite. Votre système voit B, puis A. Rien n’est cassé côté fournisseur. La garantie n’a simplement jamais couvert l’ordre.

Ordre : utilisez l’horloge de l’événement, pas celle de la livraison

Les recommandations de Wise sur les webhooks conseillent de reconstruire la chronologie à partir des horodatages d’événements ou, quand ils existent, d’identifiants de séquence strictement croissants, plutôt qu’à partir du moment où la notification a été expédiée. Sa documentation note que l’heure d’envoi peut différer du moment où l’événement s’est produit, surtout pendant les nouvelles tentatives.

En pratique :

1. Stockez l’horodatage métier ou le numéro de séquence de l’événement avec la charge utile.
2. Quand un événement arrive, comparez-le au dernier état que vous détenez pour cet objet.
3. Si l’événement entrant est plus ancien que ce que vous avez déjà appliqué, enregistrez-le mais ne le laissez pas écraser un état plus récent.

Pour un statut de paiement qui passe de en attente à confirmé, cela empêche un événement « pending » tardif de ramener un paiement confirmé en arrière.

Comment fonctionnent les nouvelles tentatives de webhook, et quand s’arrêtent-elles ?

Les politiques de nouvelle tentative varient, mais leur forme est constante : backoff exponentiel, un plafond et un arrêt définitif. Chaingateway fait exception, car il ne réessaie pas automatiquement.

Fournisseur	Comportement de nouvelle tentative (selon sa documentation)
Column	Jusqu’à 25 nouvelles tentatives en trois jours, backoff exponentiel, première nouvelle tentative une minute après la livraison échouée
Probo	Jusqu’à 12 tentatives, backoff exponentiel avec jitter complet à partir d’une base de 30 secondes, plafonné à quatre heures
Stripe	Backoff exponentiel en mode live pendant jusqu’à trois jours
Chaingateway	Aucune nouvelle tentative automatique. Les notifications échouées sont listées sur GET /api/v2/{chain}/webhooks/notifications/failed et renvoyées avec POST /api/v2/{chain}/webhooks/notifications/{id}/retry

Sources : documentation de Column, de Probo et de Stripe, consultée le 5 novembre 2026, et spécification OpenAPI de Chaingateway.

La documentation de Probo ajoute des détails utiles. Il réessaie les erreurs réseau, les délais dépassés et les réponses 408, 425, 429 ou 5xx, et il respecte un en-tête Retry-After jusqu’à son plafond. Une fois les tentatives épuisées, la livraison est marquée échouée et n’est pas remise en file.

Deux leçons en découlent. D’abord, les codes d’erreur de votre point d’accès sont des signaux : un 5xx dit à l’émetteur de réessayer, n’en renvoyez donc un que si vous voulez vraiment une nouvelle tentative. Ensuite, la fenêtre de nouvelle tentative est finie. Si votre service est hors service plus longtemps que la fenêtre, ces événements disparaissent de la file de nouvelles tentatives et vous avez besoin d’un autre moyen de les récupérer.

Pourquoi acquitter vite et traiter ensuite ?

Une livraison compte comme réussie quand vous renvoyez un statut 2xx. Column considère un événement comme livré quand il reçoit un 2xx en moins de 10 secondes et recommande de le renvoyer juste après réception, avant tout traitement conséquent. La documentation de NestJS traite le 2xx comme un succès et tout le reste, redirections, délais dépassés et connexions refusées compris, comme un échec.

Le rôle du gestionnaire est donc étroit :

1. Lire le corps brut.
2. Vérifier la signature.
3. Contrôler le type d’événement et l’identifiant.
4. Écrire l’événement dans un stockage durable (une ligne de base de données ou un message de file).
5. Renvoyer 200, 202 ou 204.

Tout le reste, comme mettre à jour des soldes, envoyer des e-mails ou appeler d’autres services, s’exécute depuis un worker qui lit ce stockage. Si vous faites le travail lent en ligne, une requête de base de données lente devient un dépassement de délai, le dépassement devient une nouvelle tentative, et la nouvelle tentative devient un doublon. Le schéma ingestion, file d’attente et diffusion est traité dans notre propre article sur les webhooks et les WebSockets.

Comment rendre les doublons inoffensifs ?

Comme la livraison au moins une fois implique des répétitions, votre gestionnaire doit être idempotent. La méthode standard est simple.

Probo conseille de vérifier la signature, de confirmer l’organisation et le type d’événement attendus, puis d’enregistrer atomiquement l’identifiant d’événement avec un index unique avant tout effet de bord. Une requête ultérieure portant un identifiant déjà enregistré est ignorée. Stripe donne le même conseil : enregistrer les identifiants d’événements traités et ignorer tout événement déjà géré. Beaucoup de fournisseurs facilitent cela en incluant un identifiant unique dans chaque charge utile. Adobe, par exemple, met un UUID dans la charge utile et le répète dans un en-tête x-adobe-event-id.

Un schéma minimal :

1. Insérez l’identifiant d’événement dans une table avec une contrainte d’unicité.
2. Si l’insertion échoue parce que l’identifiant existe, renvoyez 200 et arrêtez-vous.
3. Si elle réussit, mettez le travail en file.

L’ordre compte. Enregistrer d’abord, agir ensuite. Si vous agissez d’abord et plantez avant d’enregistrer, la nouvelle tentative répète l’action. Si vous enregistrez d’abord et plantez avant d’agir, votre worker doit reprendre les enregistrements inachevés au redémarrage, pour que l’événement ne soit pas perdu en silence.

Pour les mouvements d’argent, ajoutez une seconde couche : rendez aussi l’opération métier idempotente. Indexez un crédit de dépôt sur le hash de transaction et l’index de log, ou sur l’identifiant de paiement, pour que même un bug dans la table des événements ne puisse pas créditer deux fois le même paiement.

Comment vérifier chaque requête ?

Un point d’accès de webhook est une URL publique qui déclenche des actions dans votre système. N’importe qui peut y envoyer un POST, sauf si vous vérifiez qui a envoyé la requête.

Stripe exige une vérification avec le corps brut de la requête, l’en-tête de signature et le secret de votre point d’accès. Probo conseille d’utiliser le corps intact et de vérifier la signature avant d’analyser le JSON, puis d’appliquer un contrôle de fraîcheur de l’horodatage. Analyser et resérialiser le corps avant de vérifier est une cause classique de signatures qui ne correspondent jamais.

Une routine de vérification solide pour les fournisseurs qui signent le corps :

• Calculez le HMAC sur les octets exacts reçus, avec votre secret.
• Comparez-le à la valeur de l’en-tête avec une comparaison à temps constant.
• Rejetez les requêtes dont l’horodatage sort d’une courte fenêtre de tolérance, pour limiter les captures rejouées.
• Seulement ensuite, analysez le JSON et regardez le type d’événement.

Chaingateway fonctionne autrement. Il calcule un HMAC-SHA256 en Base64 sur le txid de la charge utile et l’envoie dans l’en-tête X-Signature. La documentation de signature montre la vérification, et notre article sur la fonction de sécurité des webhooks explique la configuration.

Comment récupérer les événements que les nouvelles tentatives ont manqués ?

Même un récepteur parfait perd des événements dans certains scénarios : une panne plus longue que la fenêtre de nouvelle tentative, un pare-feu mal configuré, un déploiement qui a renvoyé 500 pendant des heures. Les options de récupération diffèrent selon le fournisseur. Probo n’a pas de rejeu manuel et ne remet pas en file les livraisons échouées : il attend que vous alertiez sur les échecs et réconciliez avec son API. Stripe note que les opérateurs peuvent traiter manuellement un arriéré pour accélérer la récupération. Column indique que les événements manquants ou supplémentaires peuvent être récupérés par ses API d’événements quand des échecs exigent une réconciliation.

Le principe de conception commun, énoncé clairement par la documentation développeur de ThriveDesk, est de traiter les webhooks comme des notifications plutôt que comme le seul registre d’événements. Conservez les charges utiles durablement, traitez-les en asynchrone et réconciliez périodiquement les enregistrements critiques avec l’API REST.

Une tâche de réconciliation peut rester petite :

1. À intervalle régulier, listez les objets qui comptent (paiements, portefeuilles, commandes) depuis l’API du fournisseur pour la dernière fenêtre.
2. Comparez leur statut à vos propres enregistrements.
3. Appliquez les différences par le même chemin de code idempotent que celui de votre gestionnaire de webhooks.
4. Alertez si la tâche trouve souvent des trous, car cela indique un problème de point d’accès.

Comme un événement ultérieur porte souvent l’état courant complet d’un objet, un événement intermédiaire manqué peut de toute façon être écrasé par le suivant. La réconciliation couvre les cas où il n’y a pas de suivant.

Comment ces garanties s’appliquent-elles aux événements de paiement crypto ?

Les paiements on-chain relèvent les enjeux, car un événement manqué ou doublé est un crédit manqué ou doublé. Quelques habitudes aident, quel que soit le fournisseur :

• Indexez les crédits sur des identifiants de chaîne. Utilisez le hash de transaction plus l’index du transfert à l’intérieur, pas seulement l’identifiant de livraison du webhook.
• Modélisez le statut comme une progression. En attente, confirmé et final sont des états ordonnés. Ne laissez jamais un statut plus ancien écraser un statut plus récent.
• Rapprochez avec vos propres données. Cherchez l’adresse de réception ou la référence dans votre base avant de créditer, et ignorez les événements pour des adresses qui ne vous appartiennent pas.
• Réconciliez les soldes. Une comparaison planifiée de votre registre avec les soldes de portefeuille de l’API attrape tout ce que le flux d’événements a laissé tomber.

Notre guide sur le traitement automatique des dépôts avec les webhooks place ces étapes dans un flux de paiement, et le guide des webhooks Polygon montre l’alternative événementielle au polling sur une chaîne précise.

Notre point de vue

Nous construisons des webhooks pour des développeurs qui déplacent de l’argent, et nous pensons donc chaque jour aux garanties de livraison. Pour nous, aucun fournisseur honnête ne peut promettre une livraison exactement une fois, et la bonne réponse est un contrat net : les événements sont des notifications, les requêtes signées prouvent leur origine, et l’API est toujours là comme source de vérité.

C’est pourquoi nous associons des notifications d’événements en temps réel à une API REST unifiée sur plusieurs chaînes. Les webhooks vous disent que quelque chose s’est passé. L’API vous permet de le confirmer, de récupérer les données décodées de la transaction et de réconcilier quand il le faut. Nos webhooks sont signés en HMAC pour que votre récepteur puisse les vérifier, et la charge utile porte l’expéditeur, le destinataire, le contrat du jeton et le montant décodés : votre gestionnaire consacre son temps à la logique métier plutôt qu’à l’analyse de logs bruts.

Nous pensons aussi que les équipes ne devraient pas avoir à faire tourner leurs propres nœuds ni à jongler avec des points d’accès propres à chaque chaîne pour y arriver. Une intégration, un schéma de signature et une façon de consulter l’état sur Ethereum, Bitcoin, Tron, Solana, Polygon, BNB Chain et Arbitrum, cela fait moins d’endroits où un cas limite de livraison peut se cacher.

Bitblade

Construire sur des webhooks signés et multichaînes

Si vous ajoutez des paiements crypto à une application, les webhooks Chaingateway livrent des notifications d’événements blockchain avec des signatures HMAC, appuyés par une Blockchain API unique pour les portefeuilles, les transferts, les transactions décodées et les prix du gas. Les forfaits de la page des tarifs démarrent à 49 € par mois pour Plus, avec Pro à 99 €, Premium à 249 € et Enterprise à 499 € par mois, ou une facturation annuelle à partir de 490 €.

Associez le flux de webhooks au schéma de réconciliation décrit plus haut, et vous obtenez des notifications rapides avec un filet de sécurité.

Sources

• Adobe I/O Events FAQ
• Column: Events and Webhooks
• Wise Platform: Event ordering
• Probo Docs: Webhook Delivery and Recovery
• Stripe Documentation: Webhooks
• NestJS: Webhooks
• ThriveDesk Developer Docs: Retries, failures, and replay

Recommandé

• Webhooks vs WebSockets for Developers: Ingest, Queue, Fan Out Pattern
• The Use of Webhooks to Process Deposits Automatically
• New Feature to Enhance Webhook Security
• Polygon Webhooks: Get Real-Time On-Chain Events Without Polling