Recevoir des webhooks en local
Des événements live transmis à localhost, signés et sans tunnel.
Votre localhost n'est pas accessible depuis Internet. Tester un handler de webhook nécessite donc
généralement un déploiement ou un tunnel. wajub listen ne fait ni l'un ni l'autre. Il ouvre un flux
depuis votre machine vers Wajub, puis renvoie les événements reçus vers l'URL locale choisie.
wajub listen --forward-to localhost:3000/webhooks/wajubAucun de vos services n'est exposé. Il n'existe ni URL publique, ni proxy tiers, ni port entrant.
Ce que vous voyez
$ wajub listen --forward-to localhost:3000/webhooks/wajub
Ready! Streaming sandbox events for your account.
Your webhook signing secret is whsec_test_c7f543a6a4058db0dfb566dd91e922bc (^C to quit)
6:37:35 AM customer.created evt_test_NGHXbVLyHqPLOhNY3HKoXMca → 200 http://localhost:3000/webhooks/wajub
6:37:35 AM payment.created evt_test_wUpoY1JcMvjoUEs8FUdBkbuw → 200 http://localhost:3000/webhooks/wajub
6:37:36 AM payment.processing evt_test_7wP9Ty2ITqLSzVgWaU1VFH8U → 200 http://localhost:3000/webhooks/wajub
6:37:39 AM payment.succeeded evt_test_HObNwAnDRT54qb28OxW7fwQJ → 200 http://localhost:3000/webhooks/wajub
6:37:39 AM balance.updated evt_test_8pymkrpN71IQnazTsIwSxEVB → 200 http://localhost:3000/webhooks/wajub
6:37:39 AM fee.charged evt_test_u5zOJ37yKP2C0HSQZAKbUtme → 200 http://localhost:3000/webhooks/wajubLe nombre à droite est la réponse de votre propre endpoint. Un 500 indique donc l'échec de votre
handler, pas celui de la CLI. L'exécution ci-dessus correspond à un seul
wajub trigger payment.succeeded. Une commande a produit six événements, comme un véritable
paiement.
C'est le moyen le plus rapide de découvrir le nombre de types silencieusement ignorés par votre handler.
La requête transmise est un véritable webhook
La CLI signe les événements transmis avec le même mécanisme que la production et envoie les mêmes en-têtes.
| En-tête | Valeur |
|---|---|
X-Wajub-Signature | v1= suivi du HMAC |
X-Wajub-Timestamp | Secondes Unix, incluses dans la chaîne signée |
X-Wajub-Event | Le type d'événement |
X-Wajub-Delivery-Id | Cette tentative, whd_ suivi d'un UUID |
Votre code de vérification s'exécute donc réellement en local, au lieu d'être ignoré derrière un
if (process.env.NODE_ENV === 'development') qui masque un défaut jusqu'à la production.
Deux champs diffèrent d'une livraison en production. pending_webhooks vaut 0, car le flux n'est
pas un endpoint enregistré. Le User-Agent est wajub-cli au lieu de Halo/1.0. Un handler qui
adapte son comportement selon l'un de ces champs fonctionnera différemment en local et après son
déploiement. Supprimez ce piège au lieu de le contourner.
Le secret affiché au démarrage est généré pour cette exécution. Exportez-le pour que votre handler effectue la vérification sans autre modification.
export WAJUB_WEBHOOK_SECRET=whsec_test_c7f543a6a4058db0dfb566dd91e922bc
npm run devUn nouveau secret à chaque exécution devient fastidieux. Fixez-en un et placez-le une seule fois
dans votre .env.
wajub listen --forward-to localhost:3000/webhooks/wajub --secret whsec_local_dev`--skip-verify` supprime entièrement la signature
Cette option permet d'envoyer de force un payload dans un handler qui ne sait pas encore le vérifier. Elle transmet les événements sans signature. Votre endpoint ne peut alors plus distinguer Wajub de toute autre source capable de l'atteindre. Ne la laissez jamais dans un script et ne l'utilisez jamais avec un endpoint également déployé.
Options
| Option | Effet |
|---|---|
--forward-to | Destination du POST. http:// est utilisé lorsque le schéma est absent |
--events | Types séparés par des virgules, à la place de tous les événements |
--secret | Utilise ce secret de signature au lieu d'en générer un |
--skip-verify | Transmet sans signature. Consultez l'avertissement ci-dessus |
--profile | Compte et environnement dont le flux est utilisé |
# Only what your handler currently implements
wajub listen \
--forward-to localhost:3000/webhooks/wajub \
--events payment.succeeded,payment.failed,refund.succeeded
# Watch without forwarding anywhere
wajub listenSans --forward-to, la commande affiche les événements sans les envoyer. Utilisez-la pour vérifier
si un événement est émis avant d'accuser votre handler.
Quatre éléments à connaître
L'environnement provient de votre profil. Une clé de sandbox diffuse les événements de la
sandbox et une clé live les événements live. wajub doctor indique le profil utilisé. --profile
le remplace pour une exécution.
Aucun endpoint enregistré n'est nécessaire. Le flux est indépendant de POST /webhooks. Même
un compte sans endpoint transmet tous ses événements à wajub listen.
Il ne remplace pas vos endpoints enregistrés. Un endpoint live abonné aux mêmes événements continue de les recevoir. L'écoute ne détourne rien.
Aucune donnée n'est mise en mémoire tampon. Les événements produits lorsque la commande est
arrêtée ne sont pas rejoués à son démarrage. Pour les récupérer, consultez
wajub events list et renvoyez ceux qui vous intéressent.
Les événements internes n'apparaissent jamais
Les événements transaction.* sont des données de télémétrie internes au checkout. Ils sont
filtrés avant le flux, n'atteignent jamais wajub listen et ne peuvent pas être renvoyés.
La boucle
Deux terminaux suffisent, sans toucher à un téléphone.
# 1: forward everything to your handler
wajub listen --forward-to localhost:3000/webhooks/wajub
# 2: make something happen
wajub trigger payment.succeeded
wajub trigger payment.failed --amount 2500Écrivez le handler, enregistrez, puis déclenchez de nouveau l'événement. La boucle dure quelques secondes, ce qui est précisément son intérêt.