Aller au contenu
Wajub

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èglePourquoi
Vérifiez la signature avant de lire le corpsN'importe qui peut envoyer un POST à votre URL
Répondez en moins de 10 secondes, traitez ensuiteUn 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-09-01",
"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": "amina@example.com"
}
}
}

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.

ChampCe qu'il contient
idL'id de l'événement, votre clé de déduplication
eventLe type, par exemple payment.succeeded
livemodefalse en sandbox, true en live
createdLe moment où l'événement a été enregistré, au format ISO 8601
api_versionLa version selon laquelle le payload a été sérialisé
pending_webhooksLe nombre d'endpoints auxquels cet événement est destiné
requestLes identifiants de l'enregistrement de l'événement lui-même, voir la remarque ci-dessous
dataLa 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: Halo/1.0

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 cette tentative plutôt que l'événement : il change donc à chaque nouvelle tentative, alors que l'id de l'événement reste le même.

Ce qui se passe de bout en bout

  1. 1

    Vous enregistrez un endpoint

    Une URL HTTPS, dans Konsole ou via POST /webhooks. Chaque endpoint a son propre secret de signature.

  2. 2

    Quelque chose se produit

    Un paiement réussit, un transfert échoue, un litige s'ouvre. Wajub enregistre un événement.

  3. 3

    Wajub l'envoie

    Signé, à chaque endpoint abonné à ce type, avec un délai de réponse de 10 secondes.

  4. 4

    Vous répondez 2xx

    Pour toute autre réponse, ou sans réponse dans le délai, la livraison est tentée cinq fois sur seize minutes.

Pour aller plus loin

Vous voulezLisez
En recevoir un sur votre ordinateurDémarrage rapide
Prouver qu'il vient de WajubVérification de signature
Savoir quels événements existentCatalogue des événements
Comprendre un doublonNouvelles tentatives et échecs
Choisir de ne pas utiliser les webhooksWebhooks 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

Que pensez-vous de ce contenu ?