Recevoir un webhook
Un événement signé sur votre ordinateur, sans rien déployer.
Pour commencer, pas besoin d'URL publique, de service de tunnel ni d'environnement déployé. La CLI transmet les événements sandbox en temps réel à votre machine et les signe exactement comme la production : le handler que vous écrivez ici est celui que vous mettrez en production.
Écrivez l'endpoint
Il doit faire trois choses, dans cet ordre : vérifier, accuser réception, puis traiter.
# The request your endpoint will receive
POST /webhooks/wajub HTTP/1.1
X-Wajub-Signature: v1=9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
X-Wajub-Timestamp: 1748083260
X-Wajub-Event: payment.succeeded
Content-Type: application/json
{"id":"evt_…","event":"payment.succeeded","data":{…}}Répondez d'abord, traitez ensuite
Une livraison qui prend plus de 10 secondes compte comme un échec et fait l'objet d'une nouvelle tentative : un handler qui livre la commande avant de répondre la livre de nouveau à chaque tentative. Accusez réception, puis mettez le travail en file d'attente.
Branchez la CLI dessus
npm install -g @wajub/cli
wajub login
wajub listen --forward-to localhost:3000/webhooks/wajubLa CLI affiche un secret de signature au démarrage, le même à chaque exécution pour ce compte et cet
environnement. Placez-le une seule fois dans WAJUB_WEBHOOK_SECRET pendant le développement
(wajub listen --print-secret l'affiche seul) : Wajub signe avec lui les événements transférés, votre
code de vérification s'exécute donc réellement au lieu d'être ignoré en local.
| Option | Ce qu'elle fait |
|---|---|
--forward-to | Où envoyer le POST. http:// est supposé si vous l'omettez |
--events | Des types séparés par des virgules, au lieu de tous |
--print-secret | Affiche le secret de signature puis s'arrête |
--live | Obligatoire avec une clé live |
Provoquez un événement
wajub trigger pilote l'API sandbox de bout en bout et laisse le vrai événement revenir jusqu'à
vous. Ce n'est pas un payload synthétique : un paiement est réellement créé et traité.
wajub trigger --list
wajub trigger payment.succeeded
wajub trigger payment.failed --amount 2500
wajub trigger customer.created -d name="Acme Inc"Huit événements peuvent être déclenchés ainsi, et wajub trigger --list les affiche.
| Ressource | Événements |
|---|---|
| Paiements | payment.created, payment.succeeded, payment.failed, payment.cancelled |
| Remboursements | refund.succeeded, refund.failed |
| Clients | customer.created, customer.updated |
Tout ce qui sort de cette liste s'obtient de la manière habituelle : créez la ressource avec un numéro de test sandbox et laissez-la suivre son cours.
Enregistrez l'endpoint pour de bon
La CLI couvre le développement. La production nécessite un endpoint HTTPS enregistré, créé dans Konsole ou via l'API.
curl https://api.wajub.com/webhooks \
-H "Authorization: sk.xxxxxxxxxxxxxxxx…" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/webhooks/wajub",
"events": ["payment.succeeded", "payment.failed", "refund.succeeded"]
}'La réponse contient un secret whsec_, et c'est la seule fois où il est renvoyé en entier.
Enregistrez-le avant de continuer. Abonnez-vous aux événements que vous traitez plutôt qu'à tous :
un endpoint qui reçoit des types qu'il ignore doit quand même y répondre, et chacun d'eux pèse sur
votre budget de délai.
Vérifiez la livraison, pas seulement vos logs
Konsole conserve chaque tentative avec son code et son corps de réponse. Si votre handler ne s'est
jamais exécuté, la réponse se trouve dans Webhooks : un
404 signifie que l'URL est fausse, un délai dépassé signifie que vous avez répondu trop tard, et
l'absence de ligne signifie que l'événement ne correspondait pas à votre abonnement.
Webhook deliveries
| Method | Endpoint | Status | Duration | Attempt |
|---|---|---|---|---|
| POST | /webhooks/wajub | 200 | 86 ms | 1 |
Pages associées