Le verdict en trois phrases
Un webhook fiable repose sur trois piliers non négociables : vérification de signature, idempotence et file de retry. Sans eux, entre 0,5 % et 3 % des notifications de paiement se perdent — réseau, timeout provider (5 à 30 s), ou redéploiement de votre serveur. La règle d'or : ne jamais faire confiance au webhook seul, toujours doubler par un polling getStatus de secours.
Les trois piliers d'un webhook robuste
La signature garantit que l'appel vient bien du provider et pas d'un attaquant. L'idempotence garantit qu'un même événement reçu deux fois ne crée pas deux commandes. Le retry garantit qu'un échec temporaire finit par aboutir.
| Mécanisme | Rôle | Sans lui |
|---|---|---|
| Vérification signature | Authentifier l'émetteur | Faux paiements injectables |
| Idempotence (clé event) | Éviter le double traitement | Double commande / double stock |
| Stockage brut du payload | Rejouer / auditer | Impossible de déboguer |
| Retry exponentiel | Absorber les pannes réseau | Paiement perdu |
| Polling getStatus | Filet de sécurité | 100 % dépendant du webhook |
Le payload brut doit être stocké avant tout traitement métier : si votre logique plante, vous pouvez rejouer l'événement sans redemander au provider.
Retry, timeout et signature selon les providers
Répondez 200 en moins de 5 secondes, sinon le provider considère l'appel échoué et relance. Le traitement lourd (email, stock, facture) doit passer en file d'attente asynchrone.
| Provider | Signature | Timeout attente | Politique de retry |
|---|---|---|---|
| Wave | HMAC en-tête | ~10 s | plusieurs tentatives dégressives |
| Paystack | HMAC SHA512 | ~10 s | retries sur plusieurs heures |
| Flutterwave | hash secret en-tête | ~15 s | retries programmés |
| Orange Money | secret partagé | ~30 s | variable, doubler par polling |
Le retry côté provider ne suffit pas : ajoutez votre propre file avec backoff exponentiel (1 s, 2 s, 4 s, 8 s…) pour les traitements internes qui échouent après réception.
Le coût d'un webhook manqué
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.
Un paiement confirmé côté client mais non enregistré chez vous = commande fantôme. Le client a été débité, n'a rien reçu, ouvre un litige. Coût : le remboursement OU la marchandise offerte, plus le temps support (≈ 20 min), plus la réputation. Sur 1 000 commandes/mois à 2 % de webhooks perdus, ce sont 20 litiges évitables.
Mini cas pratique
Ibrahim tient un service de livraison de repas à Abidjan : 1 500 commandes/mois, panier 6 000 FCFA. Avant, il dépendait uniquement du webhook Wave : ~1,8 % perdus, soit 27 commandes/mois payées mais non confirmées. Chacune coûtait ≈ 6 000 FCFA de repas offert + 20 min support. Perte mensuelle : 162 000 FCFA + 9 h. En ajoutant idempotence + un polling getStatus toutes les 2 min sur les commandes pending, il a récupéré 26 des 27 : perte résiduelle quasi nulle.
FAQ
Que signifie rendre un webhook idempotent ? Cela veut dire qu'un même événement reçu 1, 2 ou 5 fois produit le même résultat. On stocke l'identifiant unique de l'événement et on ignore les doublons. Sans ça, un retry provider crée une double commande.
Faut-il vérifier la signature à chaque appel ? Oui, systématiquement. Sans vérification, n'importe qui connaissant votre URL peut simuler un paiement réussi. La signature (HMAC en 2026) authentifie l'émetteur en quelques millisecondes.
Pourquoi répondre en moins de 5 secondes ? Parce que la plupart des providers considèrent un temps de réponse au-delà de 5-10 s comme un échec et déclenchent un retry. Faites l'accusé de réception d'abord, le traitement lourd ensuite en asynchrone.
Le webhook peut-il vraiment échouer ? Oui : 0,5 % à 3 % en 2026 selon le réseau et la charge. D'où le filet de sécurité par polling getStatus sur toute commande restée en attente au-delà de quelques minutes.
Combien de temps garder le payload brut ? Au moins 90 jours pour le débogage et les litiges, idéalement 12 mois pour l'audit. Le stockage brut est peu coûteux et sauve des heures d'enquête.
Discutons de votre projet. Nous construisons des webhooks Wave/Orange Money à toute épreuve, avec idempotence et polling de secours. 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.
