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

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

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

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

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