Tester les webhooks en local avec keenauth webhooks listen

keenauth webhooks listen vous permet de développer un récepteur de webhooks sur votre propre machine. Elle lit l'API d'événements d'un environnement development ou staging et envoie chaque nouvel événement à une URL locale, signé exactement comme une véritable livraison de webhook (Standard Webhooks). Vous n'avez besoin ni de point de terminaison public ni de tunnel : les événements parviennent à la CLI par l'API, et la CLI les transmet sur votre machine.

Utilisation

keenauth webhooks listen --forward-to http://localhost:3000/webhooks

La commande affiche d'abord, sur la sortie d'erreur, un secret de signature pour cette session :

Signing secret for this session (shown once; not sent to KeenAuth, not stored): idp_whsec_…
Forwarding new events to http://localhost:3000/webhooks. Press Ctrl-C to stop.

Configurez votre récepteur avec ce secret pendant que la commande s'exécute, par exemple sous la forme KEENAUTH_WEBHOOK_SECRET, et vérifiez chaque livraison avec le vérificateur de webhooks du SDK (voir Vérifier les webhooks). Le secret est créé sur votre machine pour cette session uniquement : il n'est jamais envoyé à KeenAuth, n'est jamais stocké, et chaque exécution en crée un nouveau. Ce n'est pas le secret d'un point de terminaison de webhook que vous avez enregistré.

Option Description
--forward-to URL locale qui reçoit les événements (obligatoire). Elle doit être une URL http ou https sur localhost ou une adresse de boucle locale telle que 127.0.0.1 ou [::1].
--types Uniquement ces types d'événements, séparés par des virgules ou répétés.
--org Uniquement les événements de cette organisation (org_…).
--payload thin (par défaut) ou full. full inclut la ressource et nécessite également l'autorisation users:read.
--after Point de départ : latest (par défaut) ne transmet que les événements survenant à partir de maintenant ; un curseur issu de keenauth events tail commence à cet endroit.
--interval Durée entre deux vérifications lorsqu'il n'y a pas de nouvel événement, de 1s à 60s. Par défaut : 5s.
--output, -o table, json ou yaml pour les lignes de livraison. Sans cette option, la CLI affiche un tableau dans un terminal et du JSON sinon.

La commande nécessite l'autorisation events:read et fonctionne avec une clé d'API et avec une session keenauth login.

Ce que reçoit votre récepteur

Chaque événement est envoyé en POST, avec le JSON de l'événement comme corps, exactement tel que l'API d'événements l'a renvoyé, ainsi que les en-têtes suivants :

En-tête Valeur
webhook-id L'identifiant de l'événement (evt_…), identique à celui du corps.
webhook-timestamp L'heure de la livraison, en secondes Unix.
webhook-signature v1,<HMAC-SHA256 en base64> de <webhook-id>.<webhook-timestamp>.<corps> avec le secret de la session.
content-type application/json

Chaque livraison n'est tentée qu'une fois. La commande affiche une ligne par livraison, avec l'heure, le type d'événement, l'identifiant de l'événement, le code d'état que votre récepteur a répondu (ou l'erreur de connexion) et la durée. Un récepteur défaillant ou non démarré n'arrête pas la commande. Les redirections ne sont pas suivies.

Environnements

La commande ne fonctionne qu'avec les environnements development et staging. Avec un identifiant de production, elle s'arrête avant d'envoyer la moindre requête et se termine avec le code 3 :

Si le serveur refuse la requête parce que l'environnement est un environnement de production, la CLI affiche sa réponse de problème, code: test_feature_not_in_production, et se termine également avec le code 3.

Codes de sortie

Code Signification
0 Arrêt avec Ctrl-C.
1 Une erreur serveur ou une défaillance réseau vers KeenAuth, ou impossibilité de déterminer le type de l'environnement courant.
2 Erreur d'utilisation : --forward-to est absent, n'est pas une URL locale, ou un filtre ou un intervalle est invalide. Aucune requête n'a été envoyée.
3 Un identifiant de production, un identifiant absent, ou le serveur a répondu 401 ou 403.
4 L'offre n'inclut pas cette fonctionnalité (403 avec plan_feature_unavailable).