# 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

```sh
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 :

```text
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](/docs/sdk/go)). 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 :

- une clé d'API pour un environnement de production (`idp_sk_live_…` ou `idp_rk_live_…`) ;
- une session `keenauth login` dont l'environnement courant est un environnement de production.

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`). |