Le verdict en trois phrases
Les fournisseurs de paiement rejouent chaque webhook 3 à 5 fois sur 24 heures pour garantir la livraison ; sans protection, cela crée 0,3 à 0,8 % de doubles débits. La parade tient en deux mesures : une clé d'idempotence unique en base et une fenêtre de déduplication de 24 h. Bien fait, on descend le taux de doublons sous 0,02 % et on récupère les frais de remboursement — environ 1,5 % perdus à chaque transaction dupliquée.
Pourquoi les webhooks se rejouent
Un webhook est une promesse de livraison « au moins une fois », jamais « exactement une fois ». Si votre serveur répond lentement ou renvoie une erreur 5xx, le fournisseur retente. Le callback STK de M-Pesa Daraja expire en 30 secondes : si votre traitement dépasse ce délai, Safaricom considère l'appel échoué et le rejoue, même si vous avez déjà encaissé.
| Fournisseur | Nombre de tentatives | Fenêtre de retry | Vérification signature |
|---|---|---|---|
| M-Pesa Daraja | 3 à 4 | ~24 h | IP allowlist |
| Paystack | 3 à 5 | 72 h | HMAC SHA512 |
| Flutterwave | 3 à 5 | 24 h | secret hash |
| Wave | 3 à 5 | 24 h | signature header |
| Stripe | jusqu'à ~3 jours | 72 h | signing secret |
La règle d'or : répondre 200 immédiatement, puis traiter en tâche de fond. Un accusé de réception rapide coupe la moitié des rejeux inutiles.
L'architecture anti-doublon
Le cœur du système est une contrainte d'unicité en base. On stocke la clé d'idempotence (référence du fournisseur ou ID d'événement) et on refuse toute insertion en double.
| Mesure | Sans protection | Avec idempotence 2026 |
|---|---|---|
| Taux de doublons | 0,3 à 0,8 % | < 0,02 % |
| Contrainte DB unique | absente | obligatoire |
| Fenêtre de déduplication | aucune | 24 h minimum |
| Vérification de signature | optionnelle | systématique |
| Coût par doublon | ~1,5 % de frais + remboursement | 0 |
Deux vérifications sont non négociables en 2026 : valider la signature (HMAC ou secret hash) pour rejeter les faux webhooks, et rendre le traitement idempotent pour que 5 livraisons du même événement produisent exactement un débit comptabilisé.
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
Ibrahim gère une plateforme de recharge à Abidjan qui traite environ 4 500 paiements/jour. Sans clé d'idempotence, il subissait 0,5 % de doubles débits, soit ~22 clients/jour à rembourser. Chaque remboursement lui coûtait les frais d'encaissement (1,5 %) plus une heure de support. Après ajout d'une contrainte d'unicité sur l'ID d'événement et d'une fenêtre de 24 h, les doublons sont tombés à moins de 1 par jour. Sur 30 jours, il a évité ~630 remboursements et regagné la confiance de sa communauté — plus aucune capture d'écran de « double prélèvement » sur les réseaux.
FAQ
Qu'est-ce qu'une clé d'idempotence exactement ? C'est un identifiant unique attaché à une opération : si le même identifiant revient, le système renvoie le résultat déjà calculé au lieu de rejouer l'action. Pour un paiement, on utilise l'ID d'événement du fournisseur.
Pourquoi une fenêtre de 24 h et pas plus ? Parce que la plupart des fournisseurs cessent de rejouer après 24 à 72 h. Une fenêtre de 24 h couvre M-Pesa, Flutterwave et Wave ; poussez à 72 h pour Paystack et Stripe.
Faut-il vraiment vérifier la signature ? Oui. Sans vérification HMAC, n'importe qui connaissant votre URL peut simuler un paiement. La signature garantit que l'événement vient bien du fournisseur.
Quel taux de doublons viser en 2026 ? Moins de 0,02 %. Au-delà de 0,1 %, il y a presque toujours une contrainte d'unicité manquante ou un traitement synchrone trop lent qui déclenche des rejeux.
Le timeout de 30 s de Daraja est-il un problème ? Seulement si vous traitez tout dans le webhook. Répondez 200 tout de suite, mettez l'événement en file, et le timeout ne se déclenche jamais.
Discutons de votre projet. On peut auditer vos webhooks et blinder votre idempotence avant le prochain pic de trafic. 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.
