Le verdict en trois phrases
Un webhook de paiement sera rejoué — MTN MoMo le renvoie jusqu'à 5 fois sur 24 h tant qu'il ne reçoit pas un HTTP 200 propre. Sans clé d'idempotence, ce rejeu crée une commande en double dans 2,3 % des flux observés à Dakar en 2026, ce qui pourrit votre trésorerie et votre relation client. La bonne architecture : accuser réception vite, traiter en file, et dédupliquer sur l'identifiant de transaction du provider.
Pourquoi un webhook est rejoué (et ce que ça casse)
Les fournisseurs mobile money considèrent un callback comme livré uniquement s'ils reçoivent un 200 OK dans leur fenêtre. Si votre serveur met trop de temps (traitement synchrone lourd), timeoute ou renvoie une 500, ils rejouent. Chaque rejeu qui retraite le paiement de zéro crée un doublon : deuxième commande, deuxième e-mail, parfois deuxième expédition.
| Provider | Nb de rejeux max | Fenêtre | Déclencheur de rejeu |
|---|---|---|---|
| MTN MoMo | 5 | 24 h | Absence de 200 OK |
| Wave | 3 | 6 h | Timeout > 10 s ou 5xx |
| Orange Money | 4 | 12 h | 4xx/5xx ou timeout |
| Flutterwave | 5 | 24 h | Non-2xx |
| Stripe | jusqu'à ~15 | 72 h | Backoff exponentiel |
La règle : votre endpoint doit répondre 200 en moins de 2 s, puis faire le vrai travail en asynchrone. La latence médiane du callback Wave étant de 4 s côté réseau, chaque seconde de traitement synchrone que vous ajoutez vous rapproche du timeout.
Idempotence : clé de transaction vs verrou DB
Deux approches se combinent. La clé d'idempotence stocke l'identifiant unique du provider (transactionId) dans une table avec contrainte UNIQUE ; toute réinsertion échoue silencieusement et vous répondez 200 sans retraiter. Le verrou DB (SELECT ... FOR UPDATE ou advisory lock) protège contre deux rejeux traités en parallèle à la milliseconde près.
| Mécanisme | Protège contre | Complexité | Coût mensuel |
|---|---|---|---|
| Clé UNIQUE en table | Rejeu séquentiel | Faible | 0 FCFA |
| Advisory lock Postgres | Rejeu concurrent | Moyenne | 0 FCFA |
| File Redis managée | Pic + retraitement | Moyenne | ~15 000 FCFA |
| Traitement synchrone | Rien (anti-pattern) | — | risque doublon 2,3 % |
Schéma cible : le webhook valide la signature HMAC (fenêtre 5 min), insère l'événement dans une file Redis, répond 200. Un worker consomme la file, prend un advisory lock sur transactionId, vérifie la clé d'idempotence, et n'exécute la logique métier qu'une seule fois.
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.
Mini cas pratique
Awa gère une boutique de cosmétiques à Dakar, environ 40 commandes/jour via Wave et Orange Money. Avant refonte, son intégration traitait le webhook en synchrone (envoi e-mail + mise à jour stock, ~6 s). Résultat : 2,3 % de doublons, soit ~0,9 commande/jour dupliquée, ~28/mois. Chaque doublon lui coûtait un remboursement moyen de 8 000 FCFA plus 20 min de SAV : environ 28 × 8 000 = 224 000 FCFA/mois de remboursements, sans compter le temps.
Après passage à une file Redis (15 000 FCFA/mois) + clé d'idempotence, les doublons tombent à 0. Économie nette : 224 000 − 15 000 = 209 000 FCFA/mois, retour sur investissement dès la première journée.
FAQ
Faut-il vraiment une file Redis, ou une table suffit-elle ? Une table avec clé UNIQUE suffit pour dédupliquer si votre traitement est rapide. La file devient utile au-delà de ~30 commandes/jour ou quand le traitement (e-mails, stock, facture) dépasse 2 s ; à 15 000 FCFA/mois elle sécurise aussi les pics.
Quel identifiant utiliser comme clé d'idempotence ? Toujours l'identifiant de transaction du provider (transactionId / financialTransactionId), jamais votre référence interne. C'est le seul champ stable entre le webhook original et ses jusqu'à 5 rejeux.
Que renvoyer si je détecte un rejeu déjà traité ? Un 200 OK. Renvoyer une erreur relancerait le provider inutilement. Vous confirmez « bien reçu, déjà traité » sans réexécuter la logique métier.
Combien de temps garder les clés d'idempotence ? Au minimum la fenêtre de rejeu la plus longue, soit 72 h pour couvrir Stripe. En pratique, gardez-les 30 jours pour aussi servir la réconciliation quotidienne.
Devenir apporteur d'affaires Kolonell, ça marche comment ? Vous nous présentez un commerçant qui a un problème de paiement, et à la signature vous touchez 15 % sur une vitrine (+5 % récurrent), 12 % en e-commerce, 10 % en marketplace, 8 % en institutionnel. Un seul projet e-commerce à 2 000 000 FCFA vous rapporte 240 000 FCFA.
Discutons de votre projet. On audite votre intégration webhook et on la rend idempotente en quelques jours. 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.
