Webhooks Wave: idempotence, signature et sécurité (Sénégal 2026)

Le verdict en trois phrases

Le webhook est la seule source de vérité d'un paiement Wave : ne validez jamais une commande sur le retour navigateur, toujours sur l'événement serveur. Trois mécanismes le rendent fiable : vérifier la signature HMAC pour authentifier Wave, une table d'idempotence indexée sur event_id pour ne traiter chaque événement qu'une fois, et répondre 200 immédiatement (< 10 s) puis traiter en queue. Sans ces trois piliers, vous risquez double-crédit, fausses confirmations et commandes fantômes.

Les événements webhook Wave à gérer

Wave envoie plusieurs types d'événements ; votre handler doit les router proprement. Ordres de grandeur 2026 (estimation, vérifier la doc Wave Business) :

Signature, idempotence et retries

Wave signe chaque payload (HMAC) et retente en cas d'échec. Paramètres de référence 2026 :

La table d'idempotence stocke chaque event_id avec une contrainte d'unicité : si l'événement arrive deux fois (retry après timeout), l'insertion échoue et le traitement est ignoré — le crédit n'a lieu qu'une fois.

Un handler Next.js robuste

`ts

export async function POST(req: Request) {

const raw = await req.text();

const sig = req.headers.get("Wave-Signature");

if (!verifyHmac(raw, sig, process.env.WAVE_SECRET))

return new Response("invalid signature", { status: 401 });

const event = JSON.parse(raw);

const inserted = await db.insertIfAbsent("wave_events", event.id);

// Répondre 200 tout de suite, traiter ensuite en queue

if (inserted) await queue.enqueue("wave", event);

return new Response("ok", { status: 200 });

}

`

Le handler fait trois choses et rend la main : vérifier la signature, dédupliquer via insertIfAbsent, répondre 200. Tout le métier (validation commande, e-mail, stock) part en queue asynchrone pour rester sous les 10 s.

Mini cas pratique

Ibrahim, restaurateur à Dakar avec livraison, recevait 2 % de commandes payées mais jamais confirmées car son handler validait sur le retour navigateur — coupé quand le client fermait l'app. Sur 1 500 commandes/mois à 6 500 FCFA, cela représentait 30 commandes perdues, soit 195 000 FCFA/mois de litiges et remboursements manuels. En basculant sur le webhook signé + idempotent, le taux de confirmation est passé à 99,7 % et les litiges ont quasiment disparu.

FAQ

Pourquoi répondre 200 avant de traiter ?

Si votre traitement dépasse 10 s, Wave considère l'envoi en échec et déclenche un retry, ce qui crée des doublons. Répondre 200 vite puis traiter en queue casse ce cercle.

Que faire si la signature ne correspond pas ?

Renvoyer un 401 et ne rien traiter : un payload non signé correctement n'est pas authentifié et pourrait être une tentative de fraude.

Combien de temps Wave réessaie-t-il ?

En général 5 tentatives réparties sur 24 h avec un backoff exponentiel (estimation 2026). Votre table d'idempotence garantit qu'aucun de ces retries ne double-crédite.

Faut-il stocker tous les événements ?

Oui, au minimum l'event_id, le statut et l'horodatage. C'est indispensable pour la réconciliation comptable et pour rejouer un événement en cas de bug.

Discutons de votre projet. Nous livrons des webhooks Wave signés, idempotents et monitorés, prêts pour la production. WhatsApp +221 77 596 93 33.