# Webhooks lokal testen mit keenauth webhooks listen

`keenauth webhooks listen` ermöglicht es Ihnen, einen Webhook-Empfänger auf Ihrem eigenen Rechner zu entwickeln. Der Befehl liest die Event-API einer `development`- oder `staging`-Umgebung und sendet jedes neue Ereignis an eine lokale URL. Dabei wird es genauso signiert wie eine echte Webhook-Zustellung (Standard Webhooks). Sie benötigen weder einen öffentlichen Endpunkt noch einen Tunnel: Die Ereignisse kommen über die API zur CLI, und die CLI leitet sie auf Ihrem Rechner weiter.

## Verwendung

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

Der Befehl gibt zuerst ein Signaturgeheimnis für diese Sitzung auf stderr aus:

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

Konfigurieren Sie Ihren Empfänger mit diesem Geheimnis, während der Befehl läuft, zum Beispiel als `KEENAUTH_WEBHOOK_SECRET`, und prüfen Sie jede Zustellung mit dem Webhook-Verifier des SDKs (siehe [Webhooks verifizieren](/docs/sdk/go)). Das Geheimnis wird nur für diese Sitzung auf Ihrem Rechner erzeugt: Es wird nie an KeenAuth gesendet, nie gespeichert, und jeder neue Lauf erzeugt ein neues. Es ist nicht das Geheimnis eines Webhook-Endpunkts, den Sie registriert haben.

| Flag | Beschreibung |
|---|---|
| `--forward-to` | Lokale URL, die die Ereignisse empfängt (erforderlich). Sie muss eine `http`- oder `https`-URL auf `localhost` oder einer Loopback-Adresse wie `127.0.0.1` oder `[::1]` sein. |
| `--types` | Nur diese Ereignistypen, durch Kommas getrennt oder wiederholt angegeben. |
| `--org` | Nur Ereignisse dieser Organisation (`org_…`). |
| `--payload` | `thin` (Standard) oder `full`. `full` enthält die Ressource und erfordert außerdem die Berechtigung `users:read`. |
| `--after` | Wo begonnen werden soll: `latest` (Standard) leitet nur Ereignisse weiter, die ab jetzt auftreten; ein Cursor aus `keenauth events tail` beginnt dort. |
| `--interval` | Zeit zwischen zwei Prüfungen, wenn keine neuen Ereignisse vorliegen, von `1s` bis `60s`. Standard: `5s`. |
| `--output`, `-o` | `table`, `json` oder `yaml` für die Zustellungszeilen. Ohne dieses Flag gibt die CLI in einem Terminal eine Tabelle aus, sonst JSON. |

Der Befehl benötigt die Berechtigung `events:read` und funktioniert mit einem API-Schlüssel und mit einer `keenauth login`-Sitzung.

## Was Ihr Empfänger erhält

Jedes Ereignis wird als `POST` gesendet, wobei der Ereignis-JSON-Code als Body dient, genau so, wie ihn die Event-API zurückgegeben hat, mit diesen Headern:

| Header | Wert |
|---|---|
| `webhook-id` | Die Ereignis-ID (`evt_…`), dieselbe wie im Body. |
| `webhook-timestamp` | Der Zeitpunkt der Zustellung in Unix-Sekunden. |
| `webhook-signature` | `v1,<base64 HMAC-SHA256>` von `<webhook-id>.<webhook-timestamp>.<body>` mit dem Sitzungsgeheimnis. |
| `content-type` | `application/json` |

Jede Zustellung wird genau einmal versucht. Der Befehl gibt pro Zustellung eine Zeile aus, mit Zeit, Ereignistyp, Ereignis-ID, dem Statuscode, den Ihr Empfänger geantwortet hat (oder dem Verbindungsfehler), und der Dauer. Ein Empfänger, der fehlschlägt oder nicht läuft, beendet den Befehl nicht. Weiterleitungen werden nicht verfolgt.

## Umgebungen

Der Befehl funktioniert nur mit `development`- und `staging`-Umgebungen. Mit einem Produktionsberechtigungsnachweis bricht er ab, bevor er eine Anfrage sendet, und wird mit dem Code 3 beendet:

- ein API-Schlüssel für eine Produktionsumgebung (`idp_sk_live_…` oder `idp_rk_live_…`);
- eine `keenauth login`-Sitzung, deren aktuelle Umgebung eine Produktionsumgebung ist.

Lehnt der Server die Anfrage ab, weil es sich um eine Produktionsumgebung handelt, gibt die CLI seine Problemantwort aus, `code: test_feature_not_in_production`, und wird ebenfalls mit dem Code 3 beendet.

## Exit-Codes

| Code | Bedeutung |
|---|---|
| `0` | Mit Strg-C beendet. |
| `1` | Ein Serverfehler oder ein Netzwerkfehler bei der Verbindung zu KeenAuth, oder der Typ der aktuellen Umgebung konnte nicht ermittelt werden. |
| `2` | Verwendungsfehler: `--forward-to` fehlt, ist keine lokale URL, oder ein Filter oder ein Intervall ist ungültig. Es wurde keine Anfrage gesendet. |
| `3` | Ein Produktionsberechtigungsnachweis, ein fehlender Berechtigungsnachweis, oder der Server hat mit `401` oder `403` geantwortet. |
| `4` | Der Tarif enthält diese Funktion nicht (`403` mit `plan_feature_unavailable`). |