Un webhook dupliqué ne doit pas créer un second débit

La livraison au moins une fois va réessayer. Un webhook dupliqué qui publie un second débit ou une seconde ligne de boîte de réception est un incident financier et opérationnel, et non un « accusé inoffensif ». Cette page détaille le chemin d'échec : les nouvelles tentatives et les replays restent idempotents sur l'argent prépayé et la boîte de réception — il ne s'agit ni de l'essai d'idempotence d'envoi d'API ni du manuel de réessai des SMS entrants.

Articles connexes : Porte de signature et de fenêtre de replay, Contrat de webhook avant le premier envoi, lignes de débit et statut de livraison sur le même ledger.

L'idempotence est un chemin d'échec, pas un slogan

Chemin nominal : un événement signé, une acceptation, un débit. Le chemin d'échec détruit la confiance — délai dépassé, 5xx, replay du fournisseur, re-push de l'opérateur. Stockez la clé d'idempotence du Contrat de webhook avant le premier envoi avant les effets de bord : ledger, boîte de réception, CRM.

Ce qui compte comme un duplicata

L'argent ne doit pas bouger deux fois

Un second débit pour le même ID d'événement est un bogue, même si le produit « affiche toujours l'état livré ». La finance filtre par ID d'événement ou de message et ne voit qu'une seule ligne prépayée pour cette fenêtre UTC. Les effets de bord partiels après l'accusé — le CRM d'abord, le ledger ensuite — fabriquent une double vérité.

La boîte de réception ne doit pas doubler non plus

L'idempotence ne concerne pas que l'argent. Un événement entrant ou de livraison rejoué qui ouvre un second fil de boîte entraîne le support à chasser des fantômes et peut déclencher des boucles de réponse automatique. Stockez la clé de boîte avec le même ID d'événement utilisé pour le débit. Le produit et la finance partagent le rejet et la duplication.

Check-list de l'acheteur pour des webhooks sécurisés contre les duplicata

Exigez que votre fournisseur confirme le stockage de la clé d'idempotence avant l'effet de bord. Vérifiez que les pannes réseau ne génèrent pas un second débit dans la même fenêtre UTC. Exigez que les réessais renvoient le même accusé stocké sans toucher au solde. Testez avec USD 20 avant de passer à des volumes supérieurs.

Commencer avec IOSOR

Forcez une rejouée signée dans la fenêtre sur un corridor déjà facturé. Exportez l’event id à côté de l’id ledger et prouvez une seule ligne de débit plus une seule ligne inbox. Si un second débit apparaît, arrêtez ce consommateur et remboursez la ligne en trop — ne la compensez pas avec le trafic suivant. Cette porte est l’argent du replay, pas un contrôle E.164 ni un texte de livraison.

À retenir — IOSOR

Un replay n’est pas un nouvel envoi. Un event id écrit un débit.

Faites : gardez signature et fenêtre de replay, puis prouvez un débit après un POST dans la fenêtre. Ne faites pas : débiter chaque POST, ni traiter un retry réseau comme une seconde facture.