Le verdict en trois phrases
Un webhook Orange Money n'est jamais garanti unique ni ponctuel : il peut arriver deux fois, en retard de plusieurs minutes, ou se perdre. Votre code doit donc être idempotent (le même event traité deux fois ne change rien), patient (retry à backoff exponentiel) et couvert (polling de rattrapage pour les events perdus). Sur 10 000 events par mois, environ 2 % arrivent en double et 0,3 % se perdent sans filet de secours — soit 30 paiements qui disparaissent si vous n'avez pas de polling.
Les trois défaillances à couvrir
Un système de webhook fiable ne suppose jamais le meilleur cas. Il part du principe que chaque event peut échouer de trois manières, et il traite chacune.
Le doublon : l'opérateur rejoue un event parce que votre 200 est arrive trop tard, et vous recevez la même confirmation deux fois. Sans idempotence, vous créditez deux fois la commande. Le retard : un pic de trafic côté opérateur décale la livraison de plusieurs minutes ; votre système ne doit pas conclure à un échec trop vite. La perte : l'event n'arrive jamais (panne réseau des deux côtés) ; seul un polling de secours le rattrape.
| Type de défaillance | Fréquence estimée 2026 | Parade |
|---|---|---|
| Doublon | Environ 2 % des events | Clé d'idempotence transaction_id |
| Retard (> 1 min) | Environ 5 % des events | Statut "en attente", pas d'échec |
| Perte totale | Environ 0,3 % des events | Polling toutes les 15 min |
| Ordre inversé | Environ 1 % | Traiter par timestamp, pas par arrivée |
| Signature invalide | Rare mais critique | Rejet immédiat, log sécurité |
Ces chiffres sont un ordre de grandeur 2026 : ils varient selon l'opérateur et la qualité réseau, mais l'architecture doit tenir dans le pire des cas.
La stratégie de retry et le fallback polling
Quand votre serveur ne répond pas, l'opérateur rejoue selon un backoff exponentiel : les intervalles s'allongent pour ne pas noyer un serveur déjà en difficulté. De votre côté, si vous devez rejouer un traitement interne (mise en file), appliquez la même logique.
| Tentative | Délai après échec | Cumul écoulé |
|---|---|---|
| 1re | 1 s | 1 s |
| 2e | 5 s | 6 s |
| 3e | 30 s | 36 s |
| 4e | 5 min | Environ 5 min |
| 5e | 30 min | Environ 35 min |
| Fallback | Polling toutes les 15 min | En continu |
Le backoff à lui seul ne suffit pas : si l'event est définitivement perdu, aucun retry ne le fera revenir. C'est pourquoi le polling de rattrapage est indispensable. Toutes les 15 min, un job liste les commandes en statut "en attente" depuis plus de X minutes et interroge directement l'API de statut de l'opérateur. Cette double couverture — retry poussé par l'opérateur, polling tiré par vous — ramène le taux de perte réel de 0,3 % à quasiment zéro.
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
Fatou gère une plateforme de réservation à Dakar avec paiement Orange Money. En avril 2026, elle traite 10 000 events. Sans filet, elle aurait perdu environ 30 paiements (0,3 %) et double-crédite environ 200 commandes (2 %).
Après mise en place de l'idempotence par transaction_id et du polling toutes les 15 min, le bilan change : les 200 doublons sont absorbés sans effet (même clé = ignoré), et sur les 30 events perdus, le polling en rattrape 28 en moins de 15 min chacun. Les 2 restants sont traités à la réconciliation quotidienne. Résultat : zéro double crédit, deux commandes rattrapées à la main au lieu de trente perdues. Le temps passé sur les incidents de paiement tombe de 4 h à 20 min par semaine.
FAQ
Comment garantir l'idempotence ? Stockez le transaction_id de chaque event traité dans une table avec contrainte d'unicité. Avant tout traitement, vérifiez sa présence : s'il existe déjà, renvoyez 200 sans rien faire. Cela neutralise les 2 % de doublons.
Quel intervalle de polling choisir ? Toutes les 15 min pour les commandes en attente depuis plus de 5 min offre un bon compromis entre fraîcheur et charge. Un polling plus fréquent alourdit l'API opérateur sans gain réel.
Combien de retries avant d'abandonner ? Côté opérateur, jusqu'à 5 tentatives sur environ 35 min. Au-delà, ne comptez que sur le polling : un event non arrive après 5 tentatives est probablement perdu.
Faut-il traiter les events dans l'ordre d'arrivée ? Non : traitez par timestamp de l'event, pas par ordre de réception. Environ 1 % des events arrivent dans le désordre, et se fier à l'arrivée crée des incohérences de statut.
Que faire d'un event à signature invalide ? Rejet immédiat et log de sécurité. Une signature invalide signale soit un bug de configuration, soit une tentative de falsification : ne traitez jamais un tel event.
Discutons de votre projet. On construit votre gestion de webhooks Orange Money avec idempotence, retry et polling pour ne perdre aucun paiement. 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.
