Le verdict en trois phrases
Un traitement de webhook naïf (pas de déduplication, pas de vérification de signature) double silencieusement les commandes ou perd des paiements : 2 à 8 % des notifications arrivent en doublon. Un traitement durci utilise une clé d'idempotence, vérifie la signature HMAC et répond 200 en moins de 5 secondes avant de traiter en asynchrone. Sans ces trois garde-fous, votre intégration expédie deux fois, encaisse mal ou s'expose au rejeu frauduleux.
Naïf vs durci : les points de rupture
Les prestataires (Wave, Orange Money, Paystack, Flutterwave) renvoient un webhook plusieurs fois s'ils ne reçoivent pas un 200 rapide. Sans idempotence, chaque livraison déclenche une nouvelle expédition. Sans vérification de signature, n'importe qui connaissant votre URL peut simuler un « paiement réussi ». Sans réponse rapide, le prestataire considère l'appel échoué et rejoue — aggravant les doublons.
| Point | Traitement naïf | Traitement durci |
|---|---|---|
| Déduplication | Aucune | Clé d'idempotence (event id) |
| Livraisons en double | 2-8 % non gérées | Ignorées après 1re |
| Vérification signature | Absente | HMAC obligatoire |
| Temps de réponse | Traite puis répond (lent) | 200 < 5 s, traite en async |
| Fenêtre anti-rejeu | Aucune | Timestamp ± 5 min |
| Risque | Double-expédition, fraude | Maîtrisé |
La checklist de durcissement du webhook
Un webhook de paiement fiable coche six cases non négociables. Chacune neutralise une classe d'incident précise. La règle d'or : le webhook confirme l'argent, jamais le retour du navigateur — l'utilisateur peut fermer l'onglet, mais le webhook, lui, arrive.
| Garde-fou | Pourquoi | Cible 2026 |
|---|---|---|
| Vérifier la signature HMAC | Bloquer les faux paiements | 100 % des events |
| Clé d'idempotence (event id) | Ignorer les doublons | Fenêtre dédup 24-72 h |
| Répondre 200 rapidement | Éviter les retries inutiles | < 5 s |
| Traiter en asynchrone (queue) | Découpler du prestataire | File + workers |
| Fenêtre anti-rejeu (timestamp) | Bloquer le replay | ± 5 min |
| Backoff sur retry sortant | Ne pas marteler l'API | 1 min, 5 min, 30 min, 2 h |
Le backoff exponentiel s'applique quand c'est vous qui rappelez le prestataire (vérification de statut) : espacer les tentatives évite de saturer l'API et de se faire limiter (rate limit).
Mini cas pratique
Fatou exploite une boutique en ligne à Thiès : 2 000 commandes/mois, panier moyen 25 000 FCFA. Son intégration naïve reçoit 5 % de webhooks en double, soit 100 events dupliqués/mois. Sans idempotence, environ 30 % déclenchent une seconde expédition — 30 colis partis pour rien, à ~6 000 FCFA de logistique chacun, soit 180 000 FCFA/mois perdus.
Après durcissement (clé d'idempotence + signature HMAC), les 100 doublons sont ignorés dès la première livraison. Coût de l'intervention : 450 000 FCFA une fois. Amortissement : ~2,5 mois, sans compter les litiges clients et le stock brûlé évité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.
FAQ
Quel pourcentage de webhooks arrivent en double ?
En ordre de grandeur 2026, 2 à 8 % selon le prestataire et la qualité réseau. Chaque doublon non géré est un risque de double-expédition ou de double-comptabilisation.
Pourquoi répondre 200 en moins de 5 secondes ?
Parce que la plupart des prestataires considèrent l'appel échoué au-delà de ce délai et rejouent le webhook. Répondre vite puis traiter en asynchrone coupe court aux retries inutiles.
La vérification de signature est-elle vraiment obligatoire ?
Oui, sur 100 % des events. Sans HMAC, quiconque connaît votre URL de webhook peut simuler un paiement réussi et déclencher une expédition non payée.
Quelle fenêtre de déduplication choisir ?
Entre 24 et 72 heures en stockant l'identifiant d'event. Cela couvre largement les retries des prestataires, qui rejouent généralement sur quelques heures.
Quel calendrier de retry pour mes appels sortants ?
Un backoff type : 1 min, 5 min, 30 min, 2 h. Cet espacement croissant évite de marteler l'API du prestataire et de déclencher un rate limit.
Discutons de votre projet. On audite et on durcit vos webhooks de paiement : idempotence, signature, retry et anti-rejeu testés. 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.
