Le verdict en trois phrases
Une commande n'est payée que si un webhook serveur signé le confirme — jamais parce que le navigateur du client a affiche une page de succès. Le retour navigateur peut mentir : coupure réseau, onglet ferme, redirection ratée, et vous voilà avec une commande fantôme ou un client débité sans commande. La règle 2026 : vérifier la signature, accuser réception en moins de 5 s, rejouer en cas d'échec, et ne marquer "payé" que sur event confirmé.
Pourquoi le navigateur ne fait jamais foi
Le flux de paiement a deux canaux : la redirection visible par le client, et le webhook invisible envoyé de serveur à serveur. Le premier est fragile — il dépend du réseau du client, de son téléphone, de sa patience. Le second est robuste : l'opérateur (Wave, Paystack) rejoue jusqu'à ce que votre serveur réponde 200.
Si vous validez la commande sur la redirection, deux scénarios cassent tout. Un client qui ferme l'onglet après paiement : argent débité, commande jamais créée. Un client qui recharge la page de succès sans avoir payé : commande créée, aucun argent. Le webhook résout les deux parce qu'il porte l'état réel côté opérateur.
| Event à écouter | Signification | Action serveur |
|---|---|---|
| checkout.session.completed | Paiement Wave réussi | Marquer commande payée |
| charge.success | Débit confirmé (Paystack) | Déclencher la livraison |
| charge.failed | Paiement refusé | Réafficher le panier |
| refund.processed | Remboursement effectué | Déduire du CA, notifier |
| transfer.success | Payout vendeur réussi | Clôturer le versement |
| chargeback.created | Litige ouvert | Geler la commande |
Un seul event compte pour déclencher la livraison : celui qui prouve le débit. Les autres alimentent la comptabilité et le suivi.
La séquence robuste : signature, accusé, retry
Trois étapes non négociables. D'abord vérifier la signature HMAC de l'entete : elle prouve que l'appel vient bien de l'opérateur et non d'un attaquant qui simule un paiement. Ensuite répondre 200 en moins de 5 s — sinon l'opérateur considère l'envoi échoué et rejoue. Enfin traiter la logique métier de manière asynchrone pour ne jamais bloquer l'accusé.
| Paramètre | Valeur recommandée 2026 | Conséquence si ignoré |
|---|---|---|
| Timeout de réponse | Moins de 5 s | L'opérateur rejoue l'event |
| Code de réponse attendu | 200 uniquement | 4xx/5xx = retry force |
| Nombre de retries | Jusqu'à 5 sur 24 h | Event perdu si serveur down |
| Verification signature | HMAC obligatoire | Paiement falsifiable |
| Traitement métier | Asynchrone (file) | Blocage, timeout, retry |
| Idempotence | Clé transaction_id | Double traitement |
Le piège : faire tout le travail (email, PDF, stock) avant de répondre 200. Si ce travail dépasse 5 s, l'opérateur rejoue, et vous traitez deux fois. La bonne pratique : accuser d'abord, empiler la tâche dans une file, traiter après.
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 à Dakar avec paiement Wave. Première semaine : sur 500 commandes, il en compte 512 "payées" dans son admin. Douze de trop. En auditant, il découvre que ces 12 viennent de clients qui ont recharge la page de succès sans event webhook derrière.
Il bascule sur la règle "webhook signé uniquement". Résultat : les 12 fantômes disparaissent, et il rattrape même 3 commandes où le client avait ferme l'onglet mais dont le webhook charge.success était bien arrivé. Bilan réel : 491 vraies commandes encaissées, zéro fantôme, zéro client débité sans livraison. Le temps d'audit hebdomadaire tombe de 2 h à 15 min.
FAQ
Quel timeout pour l'accusé de réception ? Répondez 200 en moins de 5 s. Au-delà, la plupart des opérateurs considèrent l'appel échoué et le rejouent, ce qui peut déclencher un double traitement si vous n'avez pas d'idempotence.
Combien de fois un webhook est-il rejoué ? Jusqu'à 5 tentatives sur 24 h selon l'opérateur, avec des délais croissants. Votre serveur doit rester idempotent pour absorber ces rejeux sans créer de doublon.
Comment vérifier qu'un webhook est authentique ? Recalculez la signature HMAC à partir du corps brut et du secret partagé, puis comparez à l'entete. Un écart = requête rejetée. Sans cette vérification, n'importe qui peut simuler un paiement.
Que faire si mon serveur était hors ligne ? L'opérateur rejoue pendant 24 h, mais prévoyez un polling de rattrapage qui re-interroge le statut des commandes en attente toutes les 15 min pour les cas perdus.
Faut-il écouter tous les events ? Non : seul l'event de débit confirmé déclenche la livraison. Les autres (remboursement, litige) alimentent la comptabilité mais ne doivent jamais valider une commande.
Discutons de votre projet. On intègre vos webhooks Wave ou Paystack avec signature, retry et idempotence pour zéro commande fantôme. 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.
