Test locale dei webhook con keenauth webhooks listen

keenauth webhooks listen ti permette di sviluppare un ricevitore di webhook sulla tua macchina. Legge l'API degli eventi di un ambiente development o staging e invia ogni nuovo evento a un URL locale, firmato esattamente come una vera consegna di webhook (Standard Webhooks). Non ti serve alcun endpoint pubblico né un tunnel: gli eventi arrivano alla CLI tramite l'API, e la CLI li inoltra sulla tua macchina.

Utilizzo

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

Il comando stampa per prima cosa, su stderr, un segreto di firma per questa sessione:

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.

Configura il tuo ricevitore con quel segreto mentre il comando è in esecuzione, per esempio come KEENAUTH_WEBHOOK_SECRET, e verifica ogni consegna con il verificatore di webhook dell'SDK (vedi Verifica dei webhook). Il segreto viene creato sulla tua macchina solo per questa sessione: non viene mai inviato a KeenAuth, non viene mai memorizzato, e ogni nuova esecuzione ne crea uno nuovo. Non è il segreto di alcun endpoint webhook che hai registrato.

Flag Descrizione
--forward-to URL locale che riceve gli eventi (obbligatorio). Deve essere un URL http o https su localhost o un indirizzo loopback come 127.0.0.1 o [::1].
--types Solo questi tipi di evento, separati da virgola o ripetuti.
--org Solo gli eventi di questa organizzazione (org_…).
--payload thin (predefinito) o full. full include la risorsa e richiede anche l'autorizzazione users:read.
--after Da dove iniziare: latest (predefinito) inoltra solo gli eventi che avvengono da adesso in poi; un cursore di keenauth events tail inizia da lì.
--interval Tempo tra due controlli quando non ci sono nuovi eventi, da 1s a 60s. Predefinito: 5s.
--output, -o table, json o yaml per le righe di consegna. Senza il flag la CLI stampa una tabella su un terminale e JSON altrimenti.

Il comando richiede l'autorizzazione events:read e funziona con una chiave API e con una sessione keenauth login.

Cosa riceve il tuo ricevitore

Ogni evento viene inviato come POST con il JSON dell'evento come corpo, esattamente come lo ha restituito l'API degli eventi, e con questi header:

Header Valore
webhook-id L'ID dell'evento (evt_…), lo stesso presente nel corpo.
webhook-timestamp L'orario della consegna, in secondi Unix.
webhook-signature v1,<HMAC-SHA256 in base64> di <webhook-id>.<webhook-timestamp>.<body> con il segreto della sessione.
content-type application/json

Ogni consegna viene tentata una sola volta. Il comando stampa una riga per consegna con l'orario, il tipo di evento, l'ID dell'evento, il codice di stato con cui il tuo ricevitore ha risposto (o l'errore di connessione) e la durata. Un ricevitore che fallisce o non è in esecuzione non interrompe il comando. I reindirizzamenti non vengono seguiti.

Ambienti

Il comando funziona solo con gli ambienti development e staging. Con una credenziale di produzione si interrompe prima di inviare qualsiasi richiesta ed esce con codice 3:

Se il server rifiuta la richiesta perché l'ambiente è di produzione, la CLI stampa la sua risposta di problema, code: test_feature_not_in_production, ed esce anch'essa con codice 3.

Codici di uscita

Codice Significato
0 Arrestato con Ctrl-C.
1 Un errore del server o un errore di rete verso KeenAuth, oppure non è stato possibile determinare il tipo dell'ambiente corrente.
2 Errore di utilizzo: --forward-to manca, non è un URL locale, oppure un filtro o un intervallo non è valido. Nessuna richiesta è stata inviata.
3 Una credenziale di produzione, una credenziale mancante, oppure il server ha risposto 401 o 403.
4 Il piano non include la funzione (403 con plan_feature_unavailable).