Comment rendre un webhook de paiement ou WhatsApp idempotent ?

Attribuez à chaque webhook un identifiant unique fourni par l'expéditeur, comme un ID de commande ou un ID de message, et exécutez ses effets secondaires une seule fois. Une livraison répétée détecte que l'ID a déjà été traité et ne fait rien. Publiez le travail réel dans une file d'attente au lieu de l'exécuter directement, afin que l'expéditeur ne soit pas bloqué.

Pourquoi les webhooks arrivent-ils plusieurs fois ?

Les expéditeurs réessaient en cas de timeout, de coupures réseau ou de réponses non 2xx, et préfèrent livrer deux fois plutôt que de ne jamais livrer. Les passerelles de paiement et WhatsApp fonctionnent ainsi. Un gestionnaire qui agit à chaque livraison génère des tickets en double, envoie deux confirmations de réservation ou facture deux fois.

Quel doit être la clé d'idempotence ?

Utilisez l'identifiant que l'expéditeur garantit stable lors des réessais : l'ID de commande pour les webhooks de paiement, l'ID de message pour WhatsApp. Stockez les clés traitées et vérifiez avant d'agir. Une clé générée par vous-même à chaque livraison ne fonctionne pas, car chaque réessai serait perçu comme un nouvel événement.

Pourquoi publier dans une file d'attente plutôt que d'exécuter le travail dans le gestionnaire ?

Générer un ticket et envoyer un email directement fait attendre la passerelle sur un travail qui ne la concerne pas, ce qui provoque des timeouts et des réessais. Accusez réception rapidement, publiez un événement "paiement confirmé" dans RabbitMQ, et laissez un consommateur effectuer le travail. Une livraison répétée publie une fois ; la seconde est une opération sans effet.

Où cela est-il utilisé en production ?

Sur FindYourVibe, le webhook de paiement est idempotent sur l'ID de commande et publie dans RabbitMQ avant qu'un consommateur n'émette le ticket. Sur Trexind, chaque gestionnaire de webhook WhatsApp est idempotent sur l'ID de message, ainsi une livraison réessayée met à jour l'état une seule fois au lieu de relancer les effets secondaires de réservation ou de facturation.

Comment tester qu'un webhook est idempotent ?

Envoyez deux fois la même charge utile, idéalement en simultané, et vérifiez que l'effet secondaire s'est produit une seule fois : un ticket, une réservation, une facturation. Puis rejouez une ancienne charge après que la première a été complètement traitée. Si un compte dépasse un, la vérification de la clé est en concurrence ou manque une contrainte d'unicité.

Publié à l'origine sur sakshamjain.codes/blog/idempotent-payment-and-whatsapp-webhooks. Besoin de cette fonctionnalité ? Découvrez mes services sur NexoRush ou contactez-moi.