Le verdict en trois phrases
Un webhook n'est jamais garanti une seule fois : Orange Money peut vous notifier le même paiement 2 à 5 fois, et 3 à 8 % des événements arrivent en double. Sans garde-fou, votre système livre deux fois la commande ou double le chiffre d'affaires. La parade tient en trois briques : vérification de signature HMAC, clé d'idempotence, et table d'événements déjà traités.
Pourquoi les webhooks arrivent en double
Un webhook est un appel HTTP que l'opérateur réessaie tant qu'il n'a pas reçu un 200 OK rapide. Si votre serveur répond en 6 secondes, l'opérateur a peut-être déjà relance. Résultat : le même événement traité plusieurs fois.
| Paramètre | Ordre de grandeur 2026 | Conséquence |
|---|---|---|
| Taux d'events dupliqués | 3-8 % | Double livraison si non géré |
| Délai de livraison webhook | 2-30 s | Timeout côté opérateur |
| Fenêtre de validité signature | 5 min | Rejet si horloge décalée |
| Nombre de retries opérateur | 5 tentatives | Sur ~24h |
| Délai de réponse attendu | < 3 s | Sinon retry déclenché |
La règle d'or : répondez 200 immédiatement après avoir persiste l'événement, puis traitez la logique métier en asynchrone. Ne faites jamais la livraison, l'email et le SMS avant de répondre.
Le modèle d'idempotence
Chaque événement porte un identifiant unique (transaction_id opérateur). Avant tout traitement, on tente une insertion dans une table processed_events. Si la ligne existe déjà, on ignore et on renvoie 200.
| Étape | Action | Si duplicat |
|---|---|---|
| 1. Signature | Vérifier HMAC SHA-256 | Rejeter 401 |
| 2. Idempotence | INSERT transaction_id (unique) | Conflit -> ignorer |
| 3. Persistance | Stocker payload brut | Déjà stocké |
| 4. Ack | Répondre 200 OK | Répondre 200 OK |
| 5. Métier | Livrer / notifier (async) | Ne pas rejouer |
La contrainte d'unicité sur transaction_id en base fait tout le travail : deux webhooks concurrents pour le même paiement déclenchent une seule insertion réussie. C'est plus fiable qu'un if exists applicatif, vulnérable aux courses.
Mini cas pratique
Salif gère le checkout d'une billetterie à Ouagadougou. Un soir de concert, il encaisse 1 200 paiements Orange Money. Le pic sature son serveur : temps de réponse 7 s, donc l'opérateur relance. Il reçoit 1 356 webhooks, soit 156 doublons (13 %) ce soir-là.
Sans idempotence, il aurait émis 156 billets fantômes et fausse sa jauge de 13 %. Avec la table processed_events, les 156 doublons frappent la contrainte d'unicité et sont ignorés : 1 200 billets, zéro double. Coût évité : 156 places revendues à des clients réels, soit environ 780 000 FCFA de conflits de siège évités à 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 vérifie 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 partagé et on compare ; la signature expire après 5 minutes pour bloquer le rejeu.
Faut-il faire l'idempotence en base ou en cache ?
En base, via une contrainte d'unicité : un cache type Redis peut sauter et rouvrir la porte aux doublons. La base garantit l'atomicité même sous 2 webhooks concurrents à la milliseconde.
Combien de temps garder les événements traités ?
Gardez au moins 90 jours d'transaction_id pour couvrir les retries tardifs, qui peuvent survenir jusqu'à 24h après mais parfois plus lors d'incidents opérateur. Archivez ensuite pour ne pas gonfler la table chaude.
Que faire si aucun webhook n'arrive ?
Ne dépendez jamais du seul webhook : ajoutez un polling de statut toutes les 5 à 10 secondes pendant la fenêtre de paiement. Environ 1 à 2 % des paiements confirmés côté client n'émettent pas de webhook exploitable.
Le retry doit-il être exponentiel ?
Oui : espacez vos propres relances (10s, 30s, 2min, 10min, 1h) sur 5 tentatives et 24h. Un retry à intervalle fixe trop rapide amplifie la charge sans améliorer le taux de succès.
Discutons de votre projet. Nous mettons en place un endpoint webhook idempotent, signé et testé 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.
