Le verdict en trois phrases
Un provider mobile money rejoue ses webhooks jusqu'à 5 fois sur 24 heures : sans protection, chaque relivraison risque de créer une commande fantôme ou un double débit. Le traitement synchrone naïf plafonne à 6 % de doublons et déclenche des timeouts au-delà de 30 secondes. Une file d'attente + clé d'idempotence ramène le taux de doublon sous 0,05 % et répond toujours 200 en moins de 10 secondes.
Pourquoi un webbook est rejoué (et pourquoi c'est normal)
Les providers garantissent la livraison « au moins une fois », jamais « exactement une fois ». Si votre serveur répond lentement, plante, ou renvoie un code différent de 200, le webhook est relivré. Votre code doit donc traiter le même événement plusieurs fois sans jamais produire deux commandes.
| Paramètre 2026 | Valeur typique | Conséquence si ignoré |
|---|---|---|
| Nombre de retries provider | jusqu'à 5 fois / 24 h | Commandes dupliquées |
| Fenêtre de retry | backoff exponentiel sur 24 h | Doublons différés |
| Code de succès exigé | 200 sous 10 s | Re-livraison automatique |
| Latence médiane webhook | 800 ms | Timeout si traitement lourd |
| TTL clé d'idempotence | 72 h | Couvre toute la fenêtre retry |
| Timeout synchrone naïf | 30 s | Échec + re-livraison |
Synchrone naïf vs file d'attente idempotente
Le réflexe est de tout traiter dans la requête HTTP du webhook : vérifier le paiement, créer la commande, déclencher le payout, envoyer le SMS. C'est précisément ce qui casse sous charge.
| Critère | Synchrone naïf | File + idempotence |
|---|---|---|
| Taux de doublon | 6 % | < 0,05 % |
| Temps de réponse HTTP | 2 à 30 s | < 300 ms |
| Résistance aux retries | Aucune | Totale (clé TTL 72 h) |
| Comportement sous pic | Timeouts en cascade | Absorbé par la file |
| Risque de faux payout | Élevé | Quasi nul |
| Traçabilité | Faible | Journal par clé |
L'architecture recommandée en 5 points
- Recevoir le webhook, valider la signature, répondre 200 immédiatement (< 300 ms).
- Extraire la clé d'idempotence (référence transaction Orange Money) et vérifier si elle existe déjà.
- Si nouvelle, empiler l'événement dans une file ; si déjà vue, ignorer et répondre 200.
- Un worker dépile, crée la commande, déclenche le payout, envoie la notification.
- Stocker la clé 72 h pour couvrir toute la fenêtre de retry du provider.
Mini cas pratique
Ibrahim tient une boutique en ligne à Abidjan qui encaisse 300 commandes par jour via Orange Money. Avec son traitement synchrone naïf, 6 % des webhooks rejoués créaient des doublons, soit 18 commandes fantômes par jour. Sur un panier moyen de 15 000 FCFA, cela générait 270 000 FCFA de fausses écritures quotidiennes à annuler manuellement, plus des payouts erronés vers ses fournisseurs. Après passage en file d'attente idempotente, le taux tombe à 0,05 % — moins d'une commande douteuse tous les six jours — et son support cesse de perdre 2 heures par jour en corrections.
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
Qu'est-ce qu'une clé d'idempotence, concrètement ?
C'est un identifiant unique par événement — la référence de transaction Orange Money. Si deux webhooks portent la même clé, vous savez qu'il s'agit du même paiement et vous n'agissez qu'une fois. On la conserve 72 heures.
Pourquoi répondre 200 avant de traiter la commande ?
Parce que le provider re-livre si vous dépassez 10 secondes. En répondant 200 en moins de 300 ms puis en traitant via une file, vous évitez la cascade de retries et les timeouts.
Combien de fois un webhook peut-il être rejoué ?
Jusqu'à 5 fois sur 24 heures avec un backoff exponentiel. Votre TTL de 72 heures couvre largement cette fenêtre.
Une file d'attente est-elle indispensable pour un petit volume ?
Dès quelques dizaines de commandes par jour, oui : un seul pic ou une seule lenteur suffit à déclencher des doublons. La file découple la réception du traitement.
Comment tester l'idempotence avant la mise en production ?
En rejouant volontairement le même webhook 5 fois : le système ne doit créer qu'une commande et qu'un payout. Nous fournissons un jeu de tests de re-livraison lors de l'intégration.
Discutons de votre projet. Nous concevons vos webhooks Orange Money avec file d'attente et idempotence testée. 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.
