Le verdict en trois phrases
Un webhook de paiement mal traité, c'est 3 % de commandes créditées deux fois à Kinshasa et des confirmations manquées quand l'opérateur réessaie. La parade tient en trois piliers : vérification de signature pour bloquer les faux appels, clé d'idempotence pour ne traiter chaque événement qu'une fois, et retries avec backoff plus file morte pour ne jamais perdre une confirmation. Bien pose, le taux de double-crédit tombe à 0 % et vous cessez d'expédier des commandes fantômes.
Les cinq pannes classiques du webhook
Un webhook, c'est l'opérateur (Wave, MoMo, Paystack) qui frappe à votre porte pour dire "ce paiement est confirmé". Si vous ouvrez sans vérifier qui frappe, ou si vous comptez deux fois le même coup, tout dérape.
| Panne | Cause racine | Conséquence | Parade |
|---|---|---|---|
| Double crédit | pas de clé d'idempotence | commande x2, stock fausse | store idempotence |
| Faux paiement | endpoint non signé | fraude / spoofing | vérifier signature HMAC |
| Confirmation perdue | timeout non géré | commande jamais validée | retry + file morte |
| Ordre inversé | events hors séquence | statut incohérent | horodatage + version |
| Rejeu malveillant | pas de fenêtre temps | replay attack | timestamp +/- 5 min |
Chaque ligne correspond à un incident réel que nous voyons en audit : la bonne nouvelle, c'est que la parade est standard et testable.
Le socle technique à mettre en place
Voici les paramètres que nous configurons par défaut. Les opérateurs reessaient longtemps (Paystack jusqu'à 72 h) : votre endpoint doit être idempotent et répondre vite.
| Mécanisme | Réglage 2026 | Rôle |
|---|---|---|
| Store d'idempotence | clé = id événement, TTL 7 j | 1 traitement unique |
| Vérification signature | HMAC SHA-256, secret par env | anti-spoofing |
| Fenêtre anti-rejeu | +/- 5 minutes | bloque le replay |
| Retry backoff | 1s, 5s, 30s, 5min, 1h | absorbe les pannes |
| File morte (DLQ) | après 6 échecs | zéro perte |
| Reconcile-on-read | fallback au chargement | filet de sécurité |
| Seuil d'alerte | > 2 % échecs / 10 min | détection 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 définitivement perdu, l'application interroge l'opérateur au moment d'afficher la commande et corrige le statut.
Mini cas pratique
Ibrahim tient une boutique à Kinshasa, 1 200 commandes/mois, panier moyen 30 000 FCFA. Sans idempotence, 3 % (36 commandes) se dupliquaient : stock décrémenté en trop, clients recrédités, ~1 080 000 FCFA de valeur brassee dans le désordre chaque mois. Après mise en place du store d'idempotence, des signatures et de la DLQ : 0 double crédit sur 90 jours d'observation, et les 4 à 5 webhooks perdus par mois sont rattrapés automatiquement par le reconcile-on-read. Temps de correction manuelle : de plusieurs heures à zéro.
FAQ
Pourquoi une clé d'idempotence plutôt qu'une simple vérification "déjà traité ?" Parce que deux webhooks identiques peuvent arriver en parallèle : sans clé atomique stockée (TTL 7 jours), les deux passent le contrôle en même temps. La clé garantit un seul traitement, même en concurrence.
Comment vérifier 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 reçu et on le comparé à l'entete envoyée par l'opérateur.
Que fait la file morte exactement ? Après 6 tentatives échouées (backoff jusqu'à 1 h), l'événement est mis en file morte pour inspection humaine plutôt que perdu. Cela garantit zéro confirmation évaporée, même lors d'une panne prolongée.
Faut-il tout refaire si mon site existe déjà ? Non : on ajoute une couche webhook idempotente devant votre logique actuelle. Le branchement type prend 1 à 2 semaines, tests e2e inclus.
Discutons de votre projet. On audite vos endpoints de paiement et on sécurise vos webhooks avant le prochain double-crédit. 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.
