Le verdict en trois phrases
Une commande n'est payee que si un webhook serveur signe le confirme — jamais parce que le navigateur du client a affiche une page de succes. Le retour navigateur peut mentir : coupure reseau, onglet ferme, redirection ratee, et vous voila avec une commande fantome ou un client debite sans commande. La regle 2026 : verifier la signature, accuser reception en moins de 5 s, rejouer en cas d'echec, et ne marquer "paye" que sur event confirme.
Pourquoi le navigateur ne fait jamais foi
Le flux de paiement a deux canaux : la redirection visible par le client, et le webhook invisible envoye de serveur a serveur. Le premier est fragile — il depend du reseau du client, de son telephone, de sa patience. Le second est robuste : l'operateur (Wave, Paystack) rejoue jusqu'a ce que votre serveur reponde 200.
Si vous validez la commande sur la redirection, deux scenarios cassent tout. Un client qui ferme l'onglet apres paiement : argent debite, commande jamais creee. Un client qui recharge la page de succes sans avoir paye : commande creee, aucun argent. Le webhook resout les deux parce qu'il porte l'etat reel cote operateur.
| Event a ecouter | Signification | Action serveur |
|---|---|---|
| checkout.session.completed | Paiement Wave reussi | Marquer commande payee |
| charge.success | Debit confirme (Paystack) | Declencher la livraison |
| charge.failed | Paiement refuse | Reafficher le panier |
| refund.processed | Remboursement effectue | Deduire du CA, notifier |
| transfer.success | Payout vendeur reussi | Cloturer le versement |
| chargeback.created | Litige ouvert | Geler la commande |
Un seul event compte pour declencher la livraison : celui qui prouve le debit. Les autres alimentent la comptabilite et le suivi.
La sequence robuste : signature, accuse, retry
Trois etapes non negociables. D'abord verifier la signature HMAC de l'entete : elle prouve que l'appel vient bien de l'operateur et non d'un attaquant qui simule un paiement. Ensuite repondre 200 en moins de 5 s — sinon l'operateur considere l'envoi echoue et rejoue. Enfin traiter la logique metier de maniere asynchrone pour ne jamais bloquer l'accuse.
| Parametre | Valeur recommandee 2026 | Consequence si ignore |
|---|---|---|
| Timeout de reponse | Moins de 5 s | L'operateur rejoue l'event |
| Code de reponse attendu | 200 uniquement | 4xx/5xx = retry force |
| Nombre de retries | Jusqu'a 5 sur 24 h | Event perdu si serveur down |
| Verification signature | HMAC obligatoire | Paiement falsifiable |
| Traitement metier | Asynchrone (file) | Blocage, timeout, retry |
| Idempotence | Cle transaction_id | Double traitement |
Le piege : faire tout le travail (email, PDF, stock) avant de repondre 200. Si ce travail depasse 5 s, l'operateur rejoue, et vous traitez deux fois. La bonne pratique : accuser d'abord, empiler la tache dans une file, traiter apres.
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
Modou lance une boutique a Dakar avec paiement Wave. Premiere semaine : sur 500 commandes, il en compte 512 "payees" dans son admin. Douze de trop. En auditant, il decouvre que ces 12 viennent de clients qui ont recharge la page de succes sans event webhook derriere.
Il bascule sur la regle "webhook signe uniquement". Resultat : les 12 fantomes disparaissent, et il rattrape meme 3 commandes ou le client avait ferme l'onglet mais dont le webhook charge.success etait bien arrive. Bilan reel : 491 vraies commandes encaissees, zero fantome, zero client debite sans livraison. Le temps d'audit hebdomadaire tombe de 2 h a 15 min.
FAQ
Quel timeout pour l'accuse de reception ? Repondez 200 en moins de 5 s. Au-dela, la plupart des operateurs considerent l'appel echoue et le rejouent, ce qui peut declencher un double traitement si vous n'avez pas d'idempotence.
Combien de fois un webhook est-il rejoue ? Jusqu'a 5 tentatives sur 24 h selon l'operateur, avec des delais croissants. Votre serveur doit rester idempotent pour absorber ces rejeux sans creer de doublon.
Comment verifier qu'un webhook est authentique ? Recalculez la signature HMAC a partir du corps brut et du secret partage, puis comparez a l'entete. Un ecart = requete rejetee. Sans cette verification, n'importe qui peut simuler un paiement.
Que faire si mon serveur etait hors ligne ? L'operateur rejoue pendant 24 h, mais prevoyez un polling de rattrapage qui re-interroge le statut des commandes en attente toutes les 15 min pour les cas perdus.
Faut-il ecouter tous les events ? Non : seul l'event de debit confirme declenche la livraison. Les autres (remboursement, litige) alimentent la comptabilite mais ne doivent jamais valider une commande.
Discutons de votre projet. On integre vos webhooks Wave ou Paystack avec signature, retry et idempotence pour zero commande fantome. 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.
