Webhooks Wave Business : confirmer et reconcilier vos paiements automatiquement au Senegal

Pourquoi les webhooks sont indispensables pour un site e-commerce serieux

La plupart des petites boutiques senegalaises verifient leurs paiements Wave en ouvrant leur application manuellement. Ce modele ne passe pas a l echelle : pour 50 commandes par jour, c est impossible. Les webhooks Wave Business permettent a vos serveurs de recevoir automatiquement une notification des qu un paiement est complete, echoue ou expire. Ce guide explique comment les configurer correctement et construire un systeme de reconciliation robuste.

Comment fonctionne un webhook Wave

Un webhook est une requete HTTP POST que Wave envoie vers une URL que vous avez configuree sur votre tableau de bord Wave Business. Des que le statut d un paiement change (complete, failed, expired), Wave poste un payload JSON a 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 creation de la session — c est votre pont entre l evenement Wave et votre commande en base de donnees.

Valider la signature HMAC-SHA256

Toute requete webhook entrante doit etre validee avant traitement. Wave signe chaque requete avec un header Wave-Signature contenant une valeur HMAC-SHA256 construite a partir du corps de la requete 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)

);

}

`

Utilisez timingSafeEqual pour eviter les attaques par timing. Si la signature ne correspond pas, retournez HTTP 400 et ne traitez pas le payload.

Implementer l idempotence pour eviter les doubles livraisons

Wave peut envoyer le meme evenement plusieurs fois (nouvelle tentative en cas de timeout de votre serveur). Sans idempotence, une commande pourrait etre doublement confirmee. La solution : une table processed_events avec une contrainte UNIQUE sur l id de l evenement.

`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' });

}

`

Gerer les echecs et les timeouts

Wave considere un webhook comme echoue si votre serveur ne repond pas HTTP 200 dans les 10 secondes. En cas d echec, Wave retente avec un backoff exponentiel (apres 1 min, 5 min, 30 min, 2 h, puis abandon).

Bonnes pratiques :

• Repondre HTTP 200 immediatement, meme avant de terminer le traitement. Poussez le traitement dans une queue (Bull, BullMQ, ou meme 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_log avant tout autre traitement.

Construire une job de reconciliation

Meme avec des webhooks bien configures, des cas limites existent : serveur down au mauvais moment, timeout reseau, etc. Implementez un job de reconciliation qui tourne toutes les 15-30 minutes :

• Recuperer 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 retourne status: "complete", marquer la commande comme payee et declencher la livraison/notification.
• Si status: "expired", annuler la commande et liberer le stock.

Ce job de reconciliation rattrape tous les paiements que le webhook aurait manque. Pour une boutique qui traite 20 000 FCFA a 500 000 FCFA de transactions quotidiennes, cette securite est non-negociable.

FAQ

Combien de temps Wave conserve-t-il les evenements en cas de non-reception ?

Wave retente pendant environ 24 heures avec un backoff exponentiel. Au-dela, l evenement n est plus retente. C est pour cela que le job de reconciliation est essentiel.

Peut-on configurer plusieurs endpoints webhook pour la meme cle API ?

Wave Business permet de configurer un endpoint par cle API. Si vous avez plusieurs environnements (staging / production), utilisez des cles 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 securisees. Votre endpoint doit etre accessible sur HTTPS avec un certificat valide (Let s Encrypt suffit).

Comment tester les webhooks en local sans deployer 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 integre un systeme de paiement Wave avec webhooks et reconciliation automatique dans votre site. WhatsApp +221 77 596 93 33.