Le verdict en trois phrases
Le webhook est le moment où l'opérateur vous dit "le client a payé" — s'il est mal sécurisé, n'importe qui peut le falsifier et créer des commandes fantômes. La signature HMAC vérifiée et une clé d'idempotence sur le transaction_id empêchent la falsification et le double traitement. Sans déduplication, comptez 2 à 5 % d'événements dupliqués (rejeux réseau, retries opérateur) qui, sinon, débitent ou expédient deux fois.
Les contrôles de sécurité indispensables
Un webhook fiable enchaîne toujours les mêmes étapes : vérifier la signature, contrôler l'horloge, dédupliquer, répondre vite. Répondre 200 en moins de quelques secondes évite que l'opérateur ne rejoue l'événement en croyant à un échec.
| Contrôle | Paramètre 2026 | Risque évité |
|---|---|---|
| Signature HMAC / x-signature | Vérifiée à chaque appel | Webhook falsifié |
| Tolérance d'horloge | 5 min max | Rejeu d'un vieux message |
| Clé d'idempotence | Sur transaction_id, TTL 24 h | Double débit / double envoi |
| Whitelist IP opérateur | Liste fixe | Appels d'origine inconnue |
| Réponse rapide | 200 en < 5 s | Retries en cascade |
| Rejeu maximum | 3 tentatives | Boucle infinie |
Idempotence : le cœur du sujet
L'idempotence garantit que traiter deux fois le même événement produit le même résultat qu'une fois. Concrètement : à la réception, vous stockez le transaction_id ; si vous le revoyez avant expiration du TTL, vous répondez 200 sans re-traiter.
| Élément | Valeur recommandée 2026 |
|---|---|
| Clé d'idempotence | transaction_id opérateur |
| TTL de stockage | 24 h |
| Rejeux tolérés | Jusqu'à 3 |
| Latence webhook Wave | < 5 s |
| Taux d'événements dupliqués sans dédup | 2 - 5 % |
| Statut à renvoyer sur doublon | 200 (déjà traité) |
Mini cas pratique
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.
Ibrahim, restaurateur à Abidjan, encaisse via Wave et Flutterwave. Un soir de coupure réseau, l'opérateur rejoue 30 confirmations. Sans idempotence, 30 commandes déjà payées auraient généré 30 doubles bons de préparation en cuisine. Avec une clé sur le transaction_id et un TTL de 24 h, les 30 rejeux renvoient simplement 200 déjà traité. Sur un panier moyen de 8 000 FCFA, il évite 240 000 FCFA de plats préparés à perte et un service désorganisé.
FAQ
Pourquoi vérifier la signature si j'ai déjà une whitelist IP ? Les deux se complètent : la whitelist filtre l'origine réseau, la signature HMAC prouve que le contenu n'a pas été altéré. Un attaquant sur le bon réseau ne peut pas forger une signature valide.
Que faire si la signature est invalide ? Répondez avec un code d'erreur (401/400) et ne traitez rien. Journalisez l'événement : un pic de signatures invalides signale une tentative d'intrusion.
Combien de temps garder les transaction_id ? Un TTL de 24 h couvre largement les fenêtres de rejeu des opérateurs. Au-delà, l'événement est archivé mais plus considéré comme un doublon actif.
Le client peut-il être débité deux fois côté opérateur ? Le débit lui-même est géré par l'opérateur, pas par votre webhook. Votre risque est de traiter deux fois la commande (envoi, stock) — c'est exactement ce que l'idempotence bloque.
Faut-il répondre 200 même à un doublon ? Oui. Un doublon reconnu doit renvoyer 200 pour dire à l'opérateur "bien reçu", sinon il continue de rejouer inutilement.
Discutons de votre projet. On sécurise vos webhooks Wave, Paystack et Flutterwave avec signature, idempotence et journalisation. 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.