Aller au contenu
Wajub

Webhooks

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

Un webhook informe votre serveur du résultat d'un paiement, d'un transfert ou de tout autre changement, sans que vous ayez à le demander. Trois règles rendent une intégration correcte ; 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-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": "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. Associez un événement à votre propre commande grâce à data.reference, la reference que vous avez fournie, ou data.metadata.

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é
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

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. 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. 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 retentée pendant 72 heures au plus.

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 ?