Le verdict en trois phrases
Un webhook de paiement envoye par CinetPay, Paystack ou Flutterwave peut arriver 3 a 8 fois pour une seule transaction, car l'agregateur retente tant qu'il ne recoit pas un HTTP 200 propre. Sans cle d'idempotence stockee en base, chaque tentative recree une commande : double expedition, double email, double debit de stock. La parade tient en trois briques : verification de signature HMAC, table de deduplication indexee sur l'ID de transaction, et statut persiste (pending/success/failed).
Pourquoi un webhook arrive plusieurs fois
Les agregateurs garantissent la livraison « au moins une fois », jamais « exactement une fois ». Si votre serveur repond en 6 s, si le reseau coupe, ou si vous renvoyez un 500, le PSP considere l'evenement non livre et rejoue. C'est un comportement voulu : mieux vaut deux notifications qu'une transaction perdue. La responsabilite de la deduplication revient donc a votre code.
| PSP (ordre de grandeur 2026) | Tentatives sur 24 h | Fenetre de retry | Backoff |
|---|---|---|---|
| CinetPay | 3 a 5 | jusqu'a 24 h | croissant |
| Paystack | 5 a 8 | jusqu'a 72 h | exponentiel |
| Flutterwave | 3 a 6 | jusqu'a 48 h | exponentiel |
| PayDunya | 3 a 5 | jusqu'a 24 h | croissant |
| Wave (API directe) | 2 a 4 | jusqu'a 12 h | croissant |
La lecon : concevez pour au moins 8 rejeux possibles, meme si la moyenne est plus basse.
Le cout reel d'un doublon
Un doublon n'est pas un simple bug cosmetique. Sur une commande physique, vous perdez 100 % de la marge du deuxieme 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 paye, ni recuperable |
| Frais de livraison retour | 2 000 a 5 000 FCFA | si le client renvoie |
| Temps SAV | 15 a 30 min | par litige |
| Frais PSP non rembourses | 1,5 a 3 % | sur le montant re-traite |
| Risque de note negative | eleve | avis 1 etoile frequent |
Les trois briques techniques
1. Verifier la signature HMAC. Chaque PSP signe le corps du webhook avec votre cle secrete. Recalculez le HMAC-SHA256 et comparez avec l'en-tete recu. Un webhook non signe correctement est rejete avant tout traitement : c'est votre premiere ligne de defense 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 deduplication. Creez une table webhook_events(transaction_id UNIQUE, status, received_at). A la reception, tentez un INSERT. Si la contrainte UNIQUE saute, l'evenement est deja traite : repondez 200 et arretez. C'est la garantie d'idempotence.
3. Repondre vite, traiter apres. Accusez reception (200) en moins de 2 s, puis traitez la logique metier en tache de fond. Un traitement lourd synchrone provoque des timeouts... donc des rejeux.
Mini cas pratique
Awa gere une boutique de cosmetiques a Dakar, 900 commandes/mois via CinetPay. Avant l'idempotence, elle constatait environ 2,5 % de doublons, soit ~23 commandes/mois expediees deux fois. Panier moyen 18 000 FCFA, marge 40 % : chaque doublon lui coutait 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 fumee. Apres la mise en place d'une table de deduplication (2 jours de dev), les doublons tombent a quasi zero : l'investissement est amorti en moins de deux semaines.
FAQ
Combien de fois un webhook peut-il vraiment arriver ? Selon le PSP, de 2 a 8 tentatives sur une fenetre de 12 a 72 h. Concevez toujours pour le cas le plus large, soit au moins 8 rejeux.
Quelle cle utiliser pour dedupliquer ? L'ID de transaction du PSP (pas votre ID de commande), pose en contrainte UNIQUE. C'est le seul identifiant stable a travers tous les rejeux d'un meme paiement.
Faut-il repondre 200 meme a un doublon ? Oui. Repondre 200 en moins de 2 s stoppe les rejeux. Un 500 ou un timeout relance la sequence complete de retry.
La signature HMAC est-elle obligatoire ? Fonctionnellement non, mais sans elle n'importe qui peut simuler un paiement reussi. C'est indispensable en production : cout d'omission potentiellement 100 % du panier frauduleux.
Combien coute cette securisation ? Compter 1 a 3 jours de dev pour la table de dedup, la verification HMAC et le traitement asynchrone : un ordre de grandeur negligeable face aux pertes evitees.
Discutons de votre projet. Nous integrons des webhooks idempotents et signes pour votre agregateur mobile money, testes 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.
