Le verdict en trois phrases
Un webhook n'est jamais garanti une seule fois : Orange Money peut vous notifier le meme paiement 2 a 5 fois, et 3 a 8 % des evenements arrivent en double. Sans garde-fou, votre systeme livre deux fois la commande ou double le chiffre d'affaires. La parade tient en trois briques : verification de signature HMAC, cle d'idempotence, et table d'evenements deja traites.
Pourquoi les webhooks arrivent en double
Un webhook est un appel HTTP que l'operateur reessaie tant qu'il n'a pas recu un 200 OK rapide. Si votre serveur repond en 6 secondes, l'operateur a peut-etre deja relance. Resultat : le meme evenement traite plusieurs fois.
| Parametre | Ordre de grandeur 2026 | Consequence |
|---|---|---|
| Taux d'events dupliques | 3-8 % | Double livraison si non gere |
| Delai de livraison webhook | 2-30 s | Timeout cote operateur |
| Fenetre de validite signature | 5 min | Rejet si horloge decalee |
| Nombre de retries operateur | 5 tentatives | Sur ~24h |
| Delai de reponse attendu | < 3 s | Sinon retry declenche |
La regle d'or : repondez 200 immediatement apres avoir persiste l'evenement, puis traitez la logique metier en asynchrone. Ne faites jamais la livraison, l'email et le SMS avant de repondre.
Le modele d'idempotence
Chaque evenement porte un identifiant unique (transaction_id operateur). Avant tout traitement, on tente une insertion dans une table processed_events. Si la ligne existe deja, on ignore et on renvoie 200.
| Etape | Action | Si duplicat |
|---|---|---|
| 1. Signature | Verifier HMAC SHA-256 | Rejeter 401 |
| 2. Idempotence | INSERT transaction_id (unique) | Conflit -> ignorer |
| 3. Persistance | Stocker payload brut | Deja stocke |
| 4. Ack | Repondre 200 OK | Repondre 200 OK |
| 5. Metier | Livrer / notifier (async) | Ne pas rejouer |
La contrainte d'unicite sur transaction_id en base fait tout le travail : deux webhooks concurrents pour le meme paiement declenchent une seule insertion reussie. C'est plus fiable qu'un if exists applicatif, vulnerable aux courses.
Mini cas pratique
Salif gere le checkout d'une billetterie a Ouagadougou. Un soir de concert, il encaisse 1 200 paiements Orange Money. Le pic sature son serveur : temps de reponse 7 s, donc l'operateur relance. Il recoit 1 356 webhooks, soit 156 doublons (13 %) ce soir-la.
Sans idempotence, il aurait emis 156 billets fantomes et fausse sa jauge de 13 %. Avec la table processed_events, les 156 doublons frappent la contrainte d'unicite et sont ignores : 1 200 billets, zero double. Cout evite : 156 places revendues a des clients reels, soit environ 780 000 FCFA de conflits de siege evites a 5 000 FCFA la place.
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.
FAQ
Que verifie exactement la signature HMAC ?
Elle prouve que le webhook vient bien d'Orange Money et non d'un attaquant qui simule un paiement. On recalcule un HMAC SHA-256 du payload avec le secret partage et on compare ; la signature expire apres 5 minutes pour bloquer le rejeu.
Faut-il faire l'idempotence en base ou en cache ?
En base, via une contrainte d'unicite : un cache type Redis peut sauter et rouvrir la porte aux doublons. La base garantit l'atomicite meme sous 2 webhooks concurrents a la milliseconde.
Combien de temps garder les evenements traites ?
Gardez au moins 90 jours d'transaction_id pour couvrir les retries tardifs, qui peuvent survenir jusqu'a 24h apres mais parfois plus lors d'incidents operateur. Archivez ensuite pour ne pas gonfler la table chaude.
Que faire si aucun webhook n'arrive ?
Ne dependez jamais du seul webhook : ajoutez un polling de statut toutes les 5 a 10 secondes pendant la fenetre de paiement. Environ 1 a 2 % des paiements confirmes cote client n'emettent pas de webhook exploitable.
Le retry doit-il etre exponentiel ?
Oui : espacez vos propres relances (10s, 30s, 2min, 10min, 1h) sur 5 tentatives et 24h. Un retry a intervalle fixe trop rapide amplifie la charge sans ameliorer le taux de succes.
Discutons de votre projet. Nous mettons en place un endpoint webhook idempotent, signe et teste sous charge pour vos paiements Orange Money. 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.