Le verdict en trois phrases
Un webhook de paiement envoyé par CinetPay, Paystack ou Flutterwave peut arriver 3 à 8 fois pour une seule transaction, car l'agrégateur retente tant qu'il ne reçoit pas un HTTP 200 propre. Sans clé d'idempotence stockée en base, chaque tentative recrée une commande : double expédition, double email, double débit de stock. La parade tient en trois briques : vérification de signature HMAC, table de déduplication indexée sur l'ID de transaction, et statut persiste (pending/success/failed).
Pourquoi un webhook arrive plusieurs fois
Les agrégateurs garantissent la livraison « au moins une fois », jamais « exactement une fois ». Si votre serveur répond en 6 s, si le réseau coupe, ou si vous renvoyez un 500, le PSP considère l'événement non livré et rejoué. C'est un comportement voulu : mieux vaut deux notifications qu'une transaction perdue. La responsabilité de la déduplication revient donc à votre code.
| PSP (ordre de grandeur 2026) | Tentatives sur 24 h | Fenêtre de retry | Backoff |
|---|---|---|---|
| CinetPay | 3 à 5 | jusqu'à 24 h | croissant |
| Paystack | 5 à 8 | jusqu'à 72 h | exponentiel |
| Flutterwave | 3 à 6 | jusqu'à 48 h | exponentiel |
| PayDunya | 3 à 5 | jusqu'à 24 h | croissant |
| Wave (API directe) | 2 à 4 | jusqu'à 12 h | croissant |
La leçon : concevez pour au moins 8 rejeux possibles, même si la moyenne est plus basse.
Le coût réel d'un doublon
Un doublon n'est pas un simple bug cosmétique. Sur une commande physique, vous perdez 100 % de la marge du deuxième envoi, plus les frais de retour et le temps du service client.
| Impact d'un doublon | Estimation 2026 | Commentaire |
|---|---|---|
| Marge perdue (2e envoi) | 100 % du produit | ni payé, ni récupérable |
| Frais de livraison retour | 2 000 à 5 000 FCFA | si le client renvoie |
| Temps SAV | 15 à 30 min | par litige |
| Frais PSP non remboursés | 1,5 à 3 % | sur le montant re-traité |
| Risque de note negative | élevé | avis 1 étoile fréquent |
Les trois briques techniques
1. Vérifier la signature HMAC. Chaque PSP signé le corps du webhook avec votre clé secrète. Recalculez le HMAC-SHA256 et comparez avec l'en-tête reçu. Un webhook non signé correctement est rejeté avant tout traitement : c'est votre première ligne de défense contre les faux paiements.
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.
2. Table de déduplication. Créez une table webhook_events(transaction_id UNIQUE, status, received_at). À la réception, tentez un INSERT. Si la contrainte UNIQUE saute, l'événement est déjà traité : répondez 200 et arrêtez. C'est la garantie d'idempotence.
3. Répondre vite, traiter après. Accusez réception (200) en moins de 2 s, puis traitez la logique métier en tâche de fond. Un traitement lourd synchrone provoque des timeouts... donc des rejeux.
Mini cas pratique
Awa gère une boutique de cosmétiques à Dakar, 900 commandes/mois via CinetPay. Avant l'idempotence, elle constatait environ 2,5 % de doublons, soit ~23 commandes/mois expédiées deux fois. Panier moyen 18 000 FCFA, marge 40 % : chaque doublon lui coûtait la marge (7 200 FCFA) plus 3 000 FCFA de retour, soit 10 200 FCFA. Total : 23 x 10 200 = 234 600 FCFA/mois partis en fumée. Après la mise en place d'une table de déduplication (2 jours de dev), les doublons tombent à quasi zéro : l'investissement est amorti en moins de deux semaines.
FAQ
Combien de fois un webhook peut-il vraiment arriver ? Selon le PSP, de 2 à 8 tentatives sur une fenêtre de 12 à 72 h. Concevez toujours pour le cas le plus large, soit au moins 8 rejeux.
Quelle clé utiliser pour dédupliquer ? L'ID de transaction du PSP (pas votre ID de commande), pose en contrainte UNIQUE. C'est le seul identifiant stable à travers tous les rejeux d'un même paiement.
Faut-il répondre 200 même à un doublon ? Oui. Répondre 200 en moins de 2 s stoppe les rejeux. Un 500 ou un timeout relance la séquence complète de retry.
La signature HMAC est-elle obligatoire ? Fonctionnellement non, mais sans elle n'importe qui peut simuler un paiement réussi. C'est indispensable en production : coût d'omission potentiellement 100 % du panier frauduleux.
Combien coûte cette sécurisation ? Compter 1 à 3 jours de dev pour la table de dédup, la vérification HMAC et le traitement asynchrone : un ordre de grandeur négligeable face aux pertes évitées.
Discutons de votre projet. Nous intégrons des webhooks idempotents et signés pour votre agrégateur mobile money, testés de bout en bout. 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.
