Le verdict en trois phrases
Un webhook de paiement n'est jamais garanti unique : l'agregateur peut le renvoyer 2 a 5 fois en cas de timeout ou de retry. Sans cle d'idempotence, votre systeme credite la meme commande plusieurs fois, expedie deux fois, ou fausse votre comptabilite. La parade tient en trois reflexes : verifier la signature, stocker l'identifiant de transaction comme cle unique, et verrouiller le traitement.
Pourquoi les doublons arrivent
Les agregateurs garantissent une livraison "au moins une fois", pas "exactement une fois". Si votre serveur repond lentement ou renvoie une erreur, l'agregateur considere que le message a echoue et le rejoue. Votre code recoit alors deux fois le meme evenement de paiement.
| Cause du renvoi | Frequence relative | Consequence sans idempotence |
|---|---|---|
| Timeout de votre serveur | Frequente | Webhook rejoue 1-4 fois |
| Reponse HTTP non-200 | Frequente | Retry automatique |
| Reseau instable | Moyenne | Livraison dupliquee |
| Maintenance agregateur | Rare | Rejeu de lots |
| Bug applicatif (exception) | Variable | Double traitement |
L'ordre de grandeur observe : 1 a 3 % des transactions peuvent generer un doublon non gere si l'integration ne protege pas le traitement.
Le pattern d'idempotence, concretement
Le principe : chaque webhook porte un identifiant de transaction unique fourni par l'agregateur. Avant de traiter, vous verifiez si cet identifiant a deja ete traite. Si oui, vous repondez 200 sans rien faire ; si non, vous traitez puis enregistrez l'identifiant.
| Etape | Action technique | Effet |
|---|---|---|
| 1. Verifier la signature | Comparer le HMAC avec votre secret | Rejette les faux webhooks |
| 2. Lire l'ID transaction | Extraire la cle unique du payload | Identifie l'evenement |
| 3. Verrouiller la ligne | SELECT ... FOR UPDATE en base | Empeche le traitement concurrent |
| 4. Verifier deja traite | Chercher l'ID dans la table des paiements | Detecte le doublon |
| 5. Traiter une seule fois | Crediter, marquer payee, expedier | Action unique |
| 6. Repondre 200 vite | Acquitter pour stopper les retries | Coupe la boucle de rejeu |
Deux details cruciaux : l'ID unique doit etre contraint UNIQUE en base (la base devient le dernier rempart contre le doublon), et la reponse 200 doit etre rapide pour eviter de declencher de nouveaux retries.
Checklist d'integration robuste
Besoin d'un site web professionnel ?
Kolonell crée des sites web qui attirent des clients, optimisés pour le marché sénégalais. Devis gratuit en 2 minutes.
Verifiez la signature de chaque webhook (Wave, CinetPay, PayDunya ont chacun leur mecanisme). Utilisez l'identifiant de transaction de l'agregateur, jamais votre propre numero de commande, comme cle d'idempotence. Contraignez cet identifiant en UNIQUE. Verrouillez la transaction pendant le traitement. Repondez 200 immediatement et faites les taches lourdes en file d'attente. Loggez chaque webhook recu, traite ou ignore, pour l'audit. Testez en rejouant volontairement le meme webhook plusieurs fois.
Mini cas pratique
Moussa, developpeur d'une boutique en ligne a Thies traitant 3 000 commandes/mois, constate des plaintes de clients factures deux fois. Avant correction, environ 2 % des transactions, soit 60 commandes/mois, generaient un double traitement, pour un panier moyen de 25 000 FCFA : jusqu'a 1 500 000 FCFA de litiges et de remboursements potentiels chaque mois. Il ajoute une contrainte UNIQUE sur l'identifiant de transaction et un verrou en base. Apres deploiement, les doublons tombent a 0, le support consacre aux litiges de double facturation disparait, et la confiance des clients remonte. Cout : une journee de developpement.
FAQ
Pourquoi recevoir deux fois le meme webhook ? Parce que les agregateurs garantissent une livraison "au moins une fois". En cas de timeout ou d'erreur de votre serveur, ils rejouent l'evenement, parfois 2 a 5 fois.
Quelle cle utiliser pour l'idempotence ? L'identifiant de transaction fourni par l'agregateur, pas votre numero de commande interne. Contraignez-le en UNIQUE en base pour garantir un seul traitement.
La signature suffit-elle a eviter les doublons ? Non. La signature authentifie l'expediteur mais ne dit rien sur le fait que l'evenement a deja ete traite. Il faut combiner signature et cle d'idempotence.
Pourquoi repondre 200 rapidement ? Parce qu'une reponse lente ou en erreur declenche un nouveau retry. Acquittez vite, puis traitez les taches lourdes (e-mail, expedition) de maniere asynchrone.
Comment tester mon idempotence ? Rejouez volontairement le meme webhook plusieurs fois en environnement de test et verifiez qu'une seule commande est creditee. C'est le test minimal avant mise en production.
Discutons de votre projet. Nous integrons Wave, CinetPay et PayDunya avec idempotence, signature et retry geres de bout en bout. WhatsApp +221 77 596 93 33.
Mohamed Bah
Fondateur, Kolonell
Passionné par le digital et l'entrepreneuriat en Afrique, Mohamed accompagne les entreprises sénégalaises dans leur transformation digitale depuis 2020. Fondateur de Kolonell, il croit que chaque PME mérite une présence en ligne professionnelle et accessible.
