Le verdict en trois phrases
Un webhook de paiement n'est pas un appel unique et garanti : il est rejoue 3 a 10 fois sur 24 a 72 heures, dans le desordre, parfois apres un timeout de votre serveur. Sans cle d'idempotence, verification de signature HMAC et protection contre le rejeu, vous encaissez des doubles debits et perdez des commandes. La regle d'or : verifier la signature, dedupliquer par event id, repondre 200 vite, traiter en asynchrone, et reconcilier avec l'API de statut comme source de verite.
Pourquoi les webhooks arrivent en double
Les fournisseurs considerent un webhook comme livre uniquement si vous repondez 200 rapidement. Le moindre delai declenche un rejeu. Voici les politiques typiques 2026 (ordre de grandeur, a verifier dans la doc de chaque fournisseur).
| Fournisseur | Nb de tentatives | Fenetre de rejeu | Timeout attendu | Signature |
|---|---|---|---|---|
| Paystack | jusqu'a ~5 | ~72 h | < 10 s | x-paystack-signature (HMAC SHA512) |
| Wave | 3 a 10 | 24-48 h | < 10 s | token / signature |
| CinetPay | 3 a 8 | ~48 h | < 15 s | token de verification |
| Flutterwave | jusqu'a ~5 | ~24 h | < 10 s | verif-hash header |
| Stripe | jusqu'a ~15 sur 72 h | 72 h | < 10 s | Stripe-Signature |
Conclusion : concevez TOUJOURS votre endpoint comme s'il allait recevoir chaque evenement plusieurs fois. L'idempotence n'est pas optionnelle.
Les 5 bugs les plus frequents
| Bug | Consequence | Correctif |
|---|---|---|
| Pas de verification de signature | Faux webhook -> fausse commande payee | Verifier HMAC avant tout traitement |
| Traitement synchrone lourd | Timeout -> rejeu -> double debit | Repondre 200 vite, traiter en file async |
| Pas de deduplication | Meme event traite 2 fois | Stocker event id, ignorer si deja vu |
| Confiance au montant du payload | Montant falsifie accepte | Reconcilier via l'API de statut |
| Retour 500 sur erreur metier | Rejeu infini du fournisseur | Retourner 200 + logguer pour rejouer soi-meme |
Ces cinq erreurs representent la quasi-totalite des incidents de paiement que nous auditons chez Kolonell.
Le patron robuste en 6 etapes
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.
- Verifier la signature (HMAC) avec le secret du fournisseur, avant de lire quoi que ce soit d'autre. Signature invalide -> 401.
- Extraire l'event id et verifier en base s'il a deja ete traite. Deja vu -> repondre 200 et sortir.
- Enregistrer l'evenement brut (event id, payload, date) dans une table de journal.
- Repondre 200 immediatement, avant tout traitement metier lourd.
- Traiter en asynchrone (file d'attente) : mise a jour de la commande, envoi de la facture, notification.
- Reconcilier avec l'API
getStatusdu fournisseur comme source de verite avant de marquer "paye".
Mini cas pratique
Ibrahim vend des billets d'evenement en ligne a Abidjan. Un vendredi soir, son serveur rame sous la charge : le webhook Wave met 12 secondes a repondre, le timeout est a 10 s. Wave rejoue l'evenement 4 fois. Sans idempotence, Ibrahim cree 4 billets pour un seul paiement de 15 000 FCFA et debite... non, en realite le client n'est debite qu'une fois, mais Ibrahim envoie 4 billets valides, dont 3 seront utilises frauduleusement : perte de 45 000 FCFA sur une seule commande. Apres correction (deduplication par event id + reponse 200 immediate + traitement async), le meme scenario ne cree qu'un billet, quel que soit le nombre de rejeux. Sur un week-end a 400 billets, l'incident aurait coute plusieurs centaines de milliers de FCFA.
FAQ
Pourquoi verifier la signature si l'URL du webhook est secrete ? Parce qu'une URL n'est jamais vraiment secrete : elle fuite dans les logs, les proxies, les captures reseau. La signature HMAC prouve que le message vient bien du fournisseur et n'a pas ete falsifie. Sans elle, n'importe qui connaissant l'URL peut simuler un paiement.
Que veut dire idempotence concretement ? Cela signifie que traiter le meme evenement 1 fois ou 10 fois produit exactement le meme resultat. En pratique : stocker l'event id du fournisseur et ignorer tout evenement deja enregistre. Une commande passe a "payee" une seule fois, meme apres 10 rejeux.
Faut-il faire confiance au montant present dans le webhook ? Non. Le payload peut etre incomplet ou, en cas de faille, falsifie. Reconciliez toujours le montant et le statut via l'API de statut du fournisseur avant de livrer la commande.
Pourquoi repondre 200 avant de traiter ? Parce que le fournisseur attend un accuse rapide (souvent < 10 s). Si votre traitement metier est lent, vous depassez le timeout et declenchez des rejeux. Accusez reception d'abord, traitez ensuite en file asynchrone.
Comment tester tout ca sans vrais paiements ? Utilisez le sandbox du fournisseur et sa fonction de rejeu d'evenements. Envoyez deux fois le meme event pour verifier la deduplication, envoyez une signature invalide pour verifier le rejet 401. Kolonell livre chaque integration avec cette batterie de tests.
Discutons de votre projet. On audite vos webhooks ou on livre une integration paiement idempotente et signee, testee en sandbox. 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.
