Pourquoi les webhooks sont indispensables pour un site e-commerce sérieux
La plupart des petites boutiques sénégalaises vérifient leurs paiements Wave en ouvrant leur application manuellement. Ce modèle ne passe pas à l'échelle : pour 50 commandes par jour, c'est impossible. Les webhooks Wave Business permettent à vos serveurs de recevoir automatiquement une notification dès qu'un paiement est complète, échoue ou expiré. Ce guide explique comment les configurer correctement et construire un système de réconciliation robuste.
Comment fonctionne un webhook Wave
Un webhook est une requête HTTP POST que Wave envoie vers une URL que vous avez configurée sur votre tableau de bord Wave Business. Dès que le statut d'un paiement change (complète, failed, expired), Wave poste un payload JSON à votre endpoint.
Exemple de payload webhook Wave :
`json
{
"id": "evt_01HX9K2M",
"type": "checkout.completed",
"data": {
"id": "chk_01HX9K1A",
"client_reference": "commande_789",
"amount": "35000",
"currency": "XOF",
"when_completed": "2026-06-09T14:32:11Z"
}
}
`
Le champ client_reference est celui que vous avez fourni lors de la création de la session — c'est votre pont entre l'événement Wave et votre commande en base de données.
Valider la signature HMAC-SHA256
Toute requête webhook entrante doit être validée avant traitement. Wave signe chaque requête avec un header Wave-Signature contenant une valeur HMAC-SHA256 construite à partir du corps de la requête et de votre secret webhook.
Validation en Node.js / TypeScript :
`typescript
import crypto from 'crypto';
function validateWaveWebhook(
payload: Buffer,
signatureHeader: string,
secret: string
): boolean {
const expected = crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(expected),
Buffer.from(signatureHeader)
);
}
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.
`
Utilisez timingSafeEqual pour éviter les attaques par timing. Si la signature ne correspond pas, retournez HTTP 400 et ne traitez pas le payload.
Implémenter l'idempotence pour éviter les doubles livraisons
Wave peut envoyer le même événement plusieurs fois (nouvelle tentative en cas de timeout de votre serveur). Sans idempotence, une commande pourrait être doublement confirmée. La solution : une table processed_events avec une contrainte UNIQUE sur l id de l'événement.
`sql
CREATE TABLE processed_events (
event_id VARCHAR(64) PRIMARY KEY,
processed_at TIMESTAMPTZ DEFAULT NOW()
);
`
Avant tout traitement :
`typescript
const alreadyProcessed = await db.query(
'INSERT INTO processed_events(event_id) VALUES($1) ON CONFLICT DO NOTHING RETURNING event_id',
[event.id]
);
if (alreadyProcessed.rowCount === 0) {
return res.status(200).json({ status: 'already_processed' });
}
`
Gérer les échecs et les timeouts
Wave considère un webhook comme échoue si votre serveur ne répond pas HTTP 200 dans les 10 secondes. En cas d'échec, Wave retente avec un backoff exponentiel (après 1 min, 5 min, 30 min, 2 h, puis abandon).
Bonnes pratiques :
- Répondre HTTP 200 immédiatement, même avant de terminer le traitement. Poussez le traitement dans une queue (Bull, BullMQ, ou même un simple setImmediate pour les petits volumes).
- Monitorer votre endpoint webhook avec un outil comme Uptime Robot. Si le serveur est down pendant 2 h, vous ratez les retentatives.
- Logger chaque webhook entrant dans une table
webhook_logavant tout autre traitement.
Construire une job de réconciliation
Même avec des webhooks bien configurés, des cas limites existent : serveur down au mauvais moment, timeout réseau, etc. Implémentez un job de réconciliation qui tourne toutes les 15-30 minutes :
- Récupérer toutes les commandes en statut "en attente" depuis plus de 10 minutes.
- Pour chacune, appeler l'API Wave :
GET /v1/checkout/sessions/{session_id}. - Si l'API retourné
status: "complete", marquer la commande comme payée et déclencher la livraison/notification. - Si
status: "expired", annuler la commande et libérer le stock.
Ce job de réconciliation rattrape tous les paiements que le webhook aurait manqué. Pour une boutique qui traite 20 000 FCFA à 500 000 FCFA de transactions quotidiennes, cette sécurité est non-négociable.
FAQ
Combien de temps Wave conserve-t-il les événements en cas de non-réception ?
Wave retente pendant environ 24 heures avec un backoff exponentiel. Au-delà, l'événement n'est plus retenté. C'est pour cela que le job de réconciliation est essentiel.
Peut-on configurer plusieurs endpoints webhook pour la même clé API ?
Wave Business permet de configurer un endpoint par clé API. Si vous avez plusieurs environnements (staging / production), utilisez des clés API distinctes avec des endpoints distincts.
Faut-il HTTPS obligatoirement pour recevoir les webhooks Wave ?
Oui. Wave refuse d'envoyer des webhooks vers des URLs HTTP non sécurisées. Votre endpoint doit être accessible sur HTTPS avec un certificat validé (Let s Encrypt suffit).
Comment tester les webhooks en local sans déployer en production ?
Utilisez ngrok ou un tunnel similaire pour exposer votre localhost. ngrok donne une URL HTTPS publique que vous pouvez enregistrer temporairement dans Wave Business pour les tests.
Discutons de votre projet. Kolonell intègre un système de paiement Wave avec webhooks et réconciliation automatique dans votre site. 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.
