Le verdict en trois phrases
Un webhook mobile money n'est jamais reçu une seule fois : Orange Money peut relancer jusqu'à 5 fois sur 24 h tant qu'il n'a pas de HTTP 200 rapide. Sans protection, vous créditez la même commande plusieurs fois et le taux de doublon observé grimpe à 0,3-1,2 %. La parade tient en trois pièces : une clé d'idempotence, une table de déduplication avec TTL, et une réponse 200 en moins de 2 secondes.
Pourquoi les opérateurs renvoient plusieurs fois
Le protocole webhook est conçu pour la fiabilité : si l'opérateur ne reçoit pas d'accusé rapide, il suppose un échec et relance. Votre serveur doit donc traiter chaque événement au plus une fois, même s'il le reçoit cinq fois. C'est la définition de l'idempotence.
| Opérateur | Tentatives max | Fenêtre de retry | Timeout attendu |
|---|---|---|---|
| Orange Money | 5 | 24 h | < 2 s |
| M-Pesa Daraja | 4 | ~variable | < 5 s |
| Wave | 3-4 | 24 h | < 2 s |
| Moov Money | 5 | 24 h | < 3 s |
| Flutterwave | 3+ | ~24 h | < 15 s |
La table de déduplication : le cœur du dispositif
Stockez un identifiant unique par événement (transaction ID opérateur ou event_id). Avant de créditer, vérifiez son existence. S'il existe, répondez 200 sans rien faire. Sinon, insérez-le dans la même transaction SQL que le crédit.
| Champ | Rôle | Valeur typique |
|---|---|---|
event_id | Clé unique (PK) | UUID opérateur |
order_id | Commande liée | réf interne |
status | processed / pending | processed |
received_at | Horodatage | now() |
ttl | Expiration dédup | 24-72 h |
Un TTL de 24 à 72 h suffit : au-delà, aucun opérateur ne relance. Purgez les vieilles lignes pour garder la table légère.
Répondre vite, traiter après
Le piège classique : faire tout le traitement (crédit, e-mail, SMS) avant de répondre, ce qui dépasse les 2 secondes et déclenche un retry. La bonne pratique : valider, dédupliquer, répondre 200, puis traiter le reste en tâche de fond (file d'attente). Cela réduit les doublons observés de plus de 90 %.
Mini cas pratique
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.
Ibrahim, restaurateur à Abidjan, reçoit 1 400 paiements Orange Money par mois. Sans déduplication, à un taux de doublon de 0,8 %, ce sont 11 commandes créditées deux fois, sur un panier moyen de 9 500 FCFA, soit 104 500 FCFA de manque à gagner mensuel (remboursements, litiges, temps passé). En ajoutant une table de dédup avec clé d'idempotence, il ramène le taux à ~0 % et récupère près de 1 254 000 FCFA par an. Le développement : moins d'une journée.
FAQ
Qu'est-ce qu'une clé d'idempotence concrètement ?
C'est un identifiant unique et stable pour une opération donnée (souvent le transaction ID de l'opérateur). Il garantit que traiter le même événement deux fois produit exactement le même résultat qu'une seule fois.
Combien de fois Orange Money relance-t-il un webhook ?
En 2026, l'ordre de grandeur est de 5 tentatives réparties sur 24 h tant que votre serveur ne renvoie pas un HTTP 200 rapide. M-Pesa Daraja plafonne plutôt autour de 4 callbacks.
Quel TTL choisir pour la table de dédup ?
Entre 24 et 72 heures. C'est plus long que la fenêtre de retry de tous les opérateurs courants, donc vous êtes couvert sans laisser grossir la table indéfiniment.
Pourquoi répondre 200 en moins de 2 secondes ?
Au-delà, l'opérateur considère l'appel comme échoué et relance, multipliant les doublons. Répondez d'abord, traitez le crédit, l'e-mail et le SMS ensuite via une file d'attente.
Discutons de votre projet. Nous rendons vos webhooks Orange Money et Wave idempotents, avec table de dédup et file d'attente testées. 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.
