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 cinq fois. 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. Placez celui-ci dans WAJUB_WEBHOOK_SECRET
pendant le développement : les événements transférés sont signés avec lui, 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 |
--secret | Utilise un secret que vous avez déjà, au lieu d'en générer un |
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.kZ3qP8mWvL2xR7tB5nY4hC6dF9jS1aG0eU3i…" \
-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 of 5 |
Pages associées