Le verdict en trois phrases
Un webhook de paiement mal traite, c'est 3 % de commandes creditees deux fois a Kinshasa et des confirmations manquees quand l'operateur reessaie. La parade tient en trois piliers : verification de signature pour bloquer les faux appels, cle d'idempotence pour ne traiter chaque evenement qu'une fois, et retries avec backoff plus file morte pour ne jamais perdre une confirmation. Bien pose, le taux de double-credit tombe a 0 % et vous cessez d'expedier des commandes fantomes.
Les cinq pannes classiques du webhook
Un webhook, c'est l'operateur (Wave, MoMo, Paystack) qui frappe a votre porte pour dire "ce paiement est confirme". Si vous ouvrez sans verifier qui frappe, ou si vous comptez deux fois le meme coup, tout derape.
| Panne | Cause racine | Consequence | Parade |
|---|---|---|---|
| Double credit | pas de cle d'idempotence | commande x2, stock fausse | store idempotence |
| Faux paiement | endpoint non signe | fraude / spoofing | verifier signature HMAC |
| Confirmation perdue | timeout non gere | commande jamais validee | retry + file morte |
| Ordre inverse | events hors sequence | statut incoherent | horodatage + version |
| Rejeu malveillant | pas de fenetre temps | replay attack | timestamp +/- 5 min |
Chaque ligne correspond a un incident reel que nous voyons en audit : la bonne nouvelle, c'est que la parade est standard et testable.
Le socle technique a mettre en place
Voici les parametres que nous configurons par defaut. Les operateurs reessaient longtemps (Paystack jusqu'a 72 h) : votre endpoint doit etre idempotent et repondre vite.
| Mecanisme | Reglage 2026 | Role |
|---|---|---|
| Store d'idempotence | cle = id evenement, TTL 7 j | 1 traitement unique |
| Verification signature | HMAC SHA-256, secret par env | anti-spoofing |
| Fenetre anti-rejeu | +/- 5 minutes | bloque le replay |
| Retry backoff | 1s, 5s, 30s, 5min, 1h | absorbe les pannes |
| File morte (DLQ) | apres 6 echecs | zero perte |
| Reconcile-on-read | fallback au chargement | filet de securite |
| Seuil d'alerte | > 2 % echecs / 10 min | detection rapide |
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.
Le reconcile-on-read est le filet ultime : si un webhook est definitivement perdu, l'application interroge l'operateur au moment d'afficher la commande et corrige le statut.
Mini cas pratique
Ibrahim tient une boutique a Kinshasa, 1 200 commandes/mois, panier moyen 30 000 FCFA. Sans idempotence, 3 % (36 commandes) se dupliquaient : stock decremente en trop, clients recredites, ~1 080 000 FCFA de valeur brassee dans le desordre chaque mois. Apres mise en place du store d'idempotence, des signatures et de la DLQ : 0 double credit sur 90 jours d'observation, et les 4 a 5 webhooks perdus par mois sont rattrapes automatiquement par le reconcile-on-read. Temps de correction manuelle : de plusieurs heures a zero.
FAQ
Pourquoi une cle d'idempotence plutot qu'une simple verification "deja traite ?" Parce que deux webhooks identiques peuvent arriver en parallele : sans cle atomique stockee (TTL 7 jours), les deux passent le controle en meme temps. La cle garantit un seul traitement, meme en concurrence.
Comment verifier la signature sans exposer le secret ? Le secret vit uniquement en variable d'environnement, jamais dans le code. On recalcule le HMAC SHA-256 du corps recu et on le compare a l'entete envoyee par l'operateur.
Que fait la file morte exactement ? Apres 6 tentatives echouees (backoff jusqu'a 1 h), l'evenement est mis en file morte pour inspection humaine plutot que perdu. Cela garantit zero confirmation evaporee, meme lors d'une panne prolongee.
Faut-il tout refaire si mon site existe deja ? Non : on ajoute une couche webhook idempotente devant votre logique actuelle. Le branchement type prend 1 a 2 semaines, tests e2e inclus.
Discutons de votre projet. On audite vos endpoints de paiement et on securise vos webhooks avant le prochain double-credit. 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.
