Le verdict en trois phrases
Un operateur mobile money rejoue le meme webhook plusieurs fois : c'est une fonctionnalite, pas un bug, censee garantir la livraison. Sans cle d'idempotence, chacun de ces renvois cree un doublon de commande ou un double-encaissement, et 8 a 12 % des webhooks sont concernes. La parade tient en trois elements : une cle = l'ID de transaction operateur, une table de deduplication et un verrou de traitement.
Pourquoi les doublons existent
MTN MoMo et Orange Money renvoient un webhook tant qu'ils n'ont pas recu un accuse de reception 2xx clair. Si votre serveur repond lentement, plante en cours de traitement, ou repond apres le timeout de l'operateur, ce dernier considere l'envoi comme echoue et rejoue. Resultat : le meme paiement arrive 2, 3, parfois 4 fois.
| Metrique | Valeur (estimation 2026) | Impact |
|---|---|---|
| Webhooks dupliques observes | 8 a 12 % | Commandes fantomes |
| Fenetre de retry operateur | 24 a 72 h | Duree du risque |
| Renvois par transaction | 2 a 4 | Multiplication du doublon |
| Double-encaissement evite avec idempotence | 100 % | Objectif |
| Latence du verrou de traitement | < 50 ms | Impact perf negligeable |
Le pattern d'idempotence en trois pieces
La recette est simple et robuste :
| Piece | Role | Detail technique |
|---|---|---|
| Cle d'idempotence | Identifier de facon unique la transaction | = ID de transaction operateur |
| Table de deduplication | Memoriser les cles deja traitees | Insert unique, contrainte d'unicite |
| Verrou de traitement | Empecher deux traitements paralleles | Lock < 50 ms, libere apres |
| TTL de la cle | Purger apres la fenetre de risque | 7 jours |
Le flux : a l'arrivee d'un webhook, on tente d'inserer sa cle dans la table de deduplication. Si l'insertion reussit, c'est un webhook neuf, on le traite. Si elle echoue (cle deja presente), c'est un doublon, on repond 200 immediatement sans rien faire. La contrainte d'unicite en base fait tout le travail, meme sous forte concurrence.
Le verrou de 24 h et le TTL de 7 jours
Deux durees a bien caler. Le verrou protege contre deux renvois quasi simultanes (l'operateur peut rejouer tres vite) : il dure le temps du traitement, generalement moins de 50 ms. La cle d'idempotence doit rester en base au moins aussi longtemps que la fenetre de retry operateur, soit 24 a 72 h ; on la garde 7 jours par securite avant purge automatique. Purger trop tot rouvre la porte aux doublons tardifs.
Mini cas pratique
Aminata gere une boutique de mode en ligne a Douala qui recoit 1 500 paiements mobile money par mois. Avec un taux de duplication de 10 %, cela represente 150 webhooks dupliques mensuels. Sans idempotence, une partie se transforme en commandes fantomes : stock decremente a tort, notifications envoyees en double, parfois un double-encaissement a rembourser.
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.
En supposant que seulement 1 % de ces doublons genere une commande fantome facturee, soit 15 incidents par mois a un panier moyen de 20 000 FCFA, le risque financier et de reputation atteint 300 000 FCFA mensuels de remboursements et litiges. Avec le pattern cle unique + table de deduplication, ce chiffre tombe a zero : chaque renvoi est reconnu et ignore en moins de 50 ms.
FAQ
Quelle proportion de webhooks est vraiment dupliquee ?
Entre 8 % et 12 % selon nos observations 2026 sur MTN MoMo et Orange Money. Sur 1 500 paiements, cela fait environ 150 renvois a neutraliser chaque mois.
Quelle valeur utiliser comme cle d'idempotence ?
L'ID de transaction de l'operateur, qui est stable et unique par paiement. Ne jamais utiliser votre propre ID de commande, car un client peut relancer un paiement pour la meme commande.
Combien de temps garder la cle en base ?
Au moins la duree de la fenetre de retry operateur (24 a 72 h), idealement 7 jours avec un TTL automatique. Purger avant rouvre le risque de doublons tardifs.
Le verrou ralentit-il le traitement des paiements ?
Non. Un verrou bien concu dure moins de 50 ms, le temps d'inserer la cle. C'est imperceptible pour le client et cela previent les traitements paralleles.
L'idempotence remplace-t-elle la reconciliation ?
Non, les deux sont complementaires : l'idempotence supprime les doublons en temps reel, la reconciliation T+1 attrape les cas residuels et garantit une compta juste.
Discutons de votre projet. Nous rendons vos webhooks mobile money idempotents pour eliminer 100 % des doubles commandes. 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.
