Webhooks

Comment Wajub informe votre serveur de ce qui s'est passé, et comment vous fier à cette information.

Un paiement Mobile Money n'est pas terminé quand votre appel répond. Le payeur doit encore saisir son code PIN, l'opérateur doit encore répondre, et cela peut prendre quelques secondes ou plusieurs minutes. Un webhook vous permet de connaître le résultat sans avoir à le demander.

Trois règles rendent une intégration correcte, et le reste de cette section les détaille.

Règle	Pourquoi
Vérifiez la signature avant de lire le corps	N'importe qui peut envoyer un POST à votre URL
Répondez en moins de 10 secondes, traitez ensuite	Un handler lent déclenche une nouvelle tentative, donc un doublon
Utilisez l'id de l'événement comme clé	Le même événement peut légitimement arriver deux fois

L'enveloppe

Chaque livraison a la même forme. Le payload ne varie jamais selon le type d'événement, seul data change.

Une livraison payment.succeeded

{

"id": "evt_test_aio5DpN577tNU2vOxdmuZGhT",

"event": "payment.succeeded",

"livemode": false,

"created": "2026-05-24T10:21:09+00:00",

"api_version": "2026-10-11",

"pending_webhooks": 1,

"request": {

"id": null,

"idempotency_key": "idem_kZ3qP8mWvL2xR7tB5nY4hC6dF9jS1aG0"

"data": {

"id": "trx_CSUGajfv9xh0XQ5wu2lx",

"reference": "order-4172",

"amount": 25000,

"amount_paid": 25000,

"currency": "XAF",

"status": "succeeded",

"channel": "cm.mtn",

"customer": {

"id": "cus_test_4tRb3nP8sZcXvK2mQ9wL",

"email": "[email protected]"

}

Le type d'événement est dans `event`, pas dans `type`

Lire event.type vous renvoie undefined, et un switch sur cette valeur tombe silencieusement dans votre branche par défaut. Le champ s'appelle event. Les SDKs renvoient cette enveloppe telle quelle, la règle s'applique donc que vous l'analysiez vous-même ou non.

data est la ressource complète, octet pour octet ce que GET /payments/{id} renvoie sous transaction. Vous n'avez jamais besoin d'un second appel pour savoir ce qui s'est passé, même si en faire un reste un bon moyen de revérifier un paiement que vous jugez à forte valeur.

`request` ne contient pas votre clé d'idempotence

request.id vaut null, et request.idempotency_key est une valeur idem_… générée pour l'enregistrement de l'événement. Aucun des deux ne reflète l'en-tête Idempotency-Key que vous avez envoyé. Associez un événement à votre propre commande grâce à data.reference ou data.metadata.

Champ	Ce qu'il contient
`id`	L'id de l'événement, votre clé de déduplication
`event`	Le type, par exemple `payment.succeeded`
`livemode`	`false` en sandbox, `true` en live
`created`	Le moment où l'événement a été enregistré, au format ISO 8601
`api_version`	La version selon laquelle le payload a été sérialisé
`pending_webhooks`	Le nombre d'endpoints auxquels cet événement est destiné
`request`	Les identifiants de l'enregistrement de l'événement lui-même, voir la remarque ci-dessous
`data`	La ressource elle-même

Les en-têtes

Ce qui arrive avec le corps

X-Wajub-Signature: v1=8f3c1b0e4a7d...
X-Wajub-Timestamp: 1748081269
X-Wajub-Event: payment.succeeded
X-Wajub-Delivery-Id: whd_7Yh2MpL4tRb3nP8sZcXv
Content-Type: application/json
User-Agent: Wajub-Webhooks/1.0 (+https://wajub.com/docs/webhooks)

Les deux premiers servent à la vérification. X-Wajub-Event vous permet d'aiguiller la requête avant de l'analyser, et X-Wajub-Delivery-Id identifie la livraison de cet événement à cet endpoint : il reste le même à chaque nouvelle tentative, et diffère d'un endpoint à l'autre.

Ce qui se passe de bout en bout

1
Vous enregistrez un endpoint
Une URL, dans Konsole ou via POST /webhooks. Un endpoint live doit utiliser https:// ; un endpoint sandbox peut utiliser http://. Chaque endpoint a son propre secret de signature.
2
Quelque chose se produit
Un paiement réussit, un transfert échoue, un litige s'ouvre. Wajub enregistre un événement.
3
Wajub l'envoie
Signé, à chaque endpoint abonné à ce type, avec un délai de réponse de 10 secondes.
4
Vous répondez 2xx
Pour toute autre réponse, ou sans réponse dans le délai, la livraison est retentée avec une attente progressive, pendant 72 heures au plus.

Pour aller plus loin

Vous voulez	Lisez
En recevoir un sur votre ordinateur	Démarrage rapide
Prouver qu'il vient de Wajub	Vérification de signature
Savoir quels événements existent	Catalogue des événements
Comprendre un doublon	Nouvelles tentatives et échecs
Choisir de ne pas utiliser les webhooks	Webhooks ou polling

Pas besoin d'URL publique pour commencer

wajub listen --forward-to http://localhost:3000/webhooks transmet les événements en temps réel à votre machine, signés de la même façon qu'en production. Le démarrage rapide commence par là.

Pages associées

L'enveloppe

Les en-têtes

Ce qui se passe de bout en bout

Vous enregistrez un endpoint

Quelque chose se produit

Wajub l'envoie

Vous répondez 2xx

Pour aller plus loin

Que pensez-vous de ce contenu ?