Le verdict en trois phrases
Un opérateur mobile money rejoue le même webhook plusieurs fois : c'est une fonctionnalité, pas un bug, censée garantir la livraison. Sans clé d'idempotence, chacun de ces renvois crée un doublon de commande ou un double-encaissement, et 8 à 12 % des webhooks sont concernés. La parade tient en trois éléments : une clé = l'ID de transaction opérateur, une table de déduplication et un verrou de traitement.
Pourquoi les doublons existent
MTN MoMo et Orange Money renvoient un webhook tant qu'ils n'ont pas reçu un accusé de réception 2xx clair. Si votre serveur répond lentement, plante en cours de traitement, ou répond après le timeout de l'opérateur, ce dernier considère l'envoi comme échoué et rejoue. Résultat : le même paiement arrive 2, 3, parfois 4 fois.
| Métrique | Valeur (estimation 2026) | Impact |
|---|---|---|
| Webhooks dupliqués observés | 8 à 12 % | Commandes fantômes |
| Fenêtre de retry opérateur | 24 à 72 h | Durée du risque |
| Renvois par transaction | 2 à 4 | Multiplication du doublon |
| Double-encaissement évite avec idempotence | 100 % | Objectif |
| Latence du verrou de traitement | < 50 ms | Impact perf négligeable |
Le pattern d'idempotence en trois pièces
La recette est simple et robuste :
| Pièce | Rôle | Détail technique |
|---|---|---|
| Clé d'idempotence | Identifier de façon unique la transaction | = ID de transaction opérateur |
| Table de déduplication | Mémoriser les clés déjà traitées | Insert unique, contrainte d'unicité |
| Verrou de traitement | Empêcher deux traitements parallèles | Lock < 50 ms, libère après |
| TTL de la clé | Purger après la fenêtre de risque | 7 jours |
Le flux : à l'arrivée d'un webhook, on tente d'insérer sa clé dans la table de déduplication. Si l'insertion réussit, c'est un webhook neuf, on le traité. Si elle échoue (clé déjà présente), c'est un doublon, on répond 200 immédiatement sans rien faire. La contrainte d'unicité en base fait tout le travail, même sous forte concurrence.
Le verrou de 24 h et le TTL de 7 jours
Deux durées a bien caler. Le verrou protège contre deux renvois quasi simultanés (l'opérateur peut rejouer très vite) : il dure le temps du traitement, généralement moins de 50 ms. La clé d'idempotence doit rester en base au moins aussi longtemps que la fenêtre de retry opérateur, soit 24 à 72 h ; on la garde 7 jours par sécurité avant purge automatique. Purger trop tôt rouvre la porte aux doublons tardifs.
Mini cas pratique
Aminata gère une boutique de mode en ligne à Douala qui reçoit 1 500 paiements mobile money par mois. Avec un taux de duplication de 10 %, cela représente 150 webhooks dupliqués mensuels. Sans idempotence, une partie se transforme en commandes fantômes : stock décrémenté à tort, notifications envoyées en double, parfois un double-encaissement à 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 génère une commande fantôme facturée, soit 15 incidents par mois à un panier moyen de 20 000 FCFA, le risque financier et de réputation atteint 300 000 FCFA mensuels de remboursements et litiges. Avec le pattern clé unique + table de déduplication, ce chiffre tombe à zéro : chaque renvoi est reconnu et ignoré en moins de 50 ms.
FAQ
Quelle proportion de webhooks est vraiment dupliquée ?
Entre 8 % et 12 % selon nos observations 2026 sur MTN MoMo et Orange Money. Sur 1 500 paiements, cela fait environ 150 renvois à neutraliser chaque mois.
Quelle valeur utiliser comme clé d'idempotence ?
L'ID de transaction de l'opérateur, qui est stable et unique par paiement. Ne jamais utiliser votre propre ID de commande, car un client peut relancer un paiement pour la même commande.
Combien de temps garder la clé en base ?
Au moins la durée de la fenêtre de retry opérateur (24 à 72 h), idéalement 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 conçu dure moins de 50 ms, le temps d'insérer la clé. C'est imperceptible pour le client et cela prévient les traitements parallèles.
L'idempotence remplace-t-elle la réconciliation ?
Non, les deux sont complémentaires : l'idempotence supprime les doublons en temps réel, la réconciliation T+1 attrape les cas résiduels et garantit une compta juste.
Discutons de votre projet. Nous rendons vos webhooks mobile money idempotents pour éliminer 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.
