Prueba de webhooks en local con keenauth webhooks listen

keenauth webhooks listen le permite desarrollar un receptor de webhooks en su propia máquina. Lee la API de eventos de un entorno development o staging y envía cada evento nuevo a una URL local, firmado exactamente igual que una entrega de webhook real (Standard Webhooks). No necesita un endpoint público ni un túnel: los eventos llegan a la CLI a través de la API, y la CLI los reenvía en su máquina.

Uso

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

El comando imprime primero, en la salida de error estándar, un secreto de firma para esta sesión:

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.

Configure su receptor con ese secreto mientras el comando se ejecuta, por ejemplo como KEENAUTH_WEBHOOK_SECRET, y verifique cada entrega con el verificador de webhooks del SDK (véase Verificar webhooks). El secreto se crea en su máquina solo para esta sesión: nunca se envía a KeenAuth, nunca se almacena, y cada ejecución crea uno nuevo. No es el secreto de ningún endpoint de webhook que haya registrado.

Opción Descripción
--forward-to URL local que recibe los eventos (obligatoria). Debe ser una URL http o https en localhost o en una dirección de bucle local, como 127.0.0.1 o [::1].
--types Solo estos tipos de evento, separados por comas o repetidos.
--org Solo los eventos de esta organización (org_…).
--payload thin (predeterminado) o full. full incluye el recurso y además requiere el permiso users:read.
--after Desde dónde empezar: latest (predeterminado) reenvía solo los eventos que ocurran a partir de ahora; un cursor de keenauth events tail empieza desde ahí.
--interval Tiempo entre dos comprobaciones cuando no hay eventos nuevos, de 1s a 60s. Predeterminado: 5s.
--output, -o table, json o yaml para las líneas de entrega. Sin esta opción, la CLI muestra una tabla en un terminal y JSON en caso contrario.

El comando necesita el permiso events:read y funciona con una clave de API y con una sesión de keenauth login.

Lo que recibe su receptor

Cada evento se envía como POST con el JSON del evento como cuerpo, exactamente como lo devolvió la API de eventos, y con estas cabeceras:

Cabecera Valor
webhook-id El ID del evento (evt_…), igual que en el cuerpo.
webhook-timestamp La hora de la entrega, en segundos Unix.
webhook-signature v1,<HMAC-SHA256 en base64> de <webhook-id>.<webhook-timestamp>.<body> con el secreto de la sesión.
content-type application/json

Cada entrega se intenta una sola vez. El comando imprime una línea por entrega con la hora, el tipo de evento, el ID del evento, el código de estado que respondió su receptor (o el error de conexión) y la duración. Un receptor que falla o que no está en ejecución no detiene el comando. No se siguen las redirecciones.

Entornos

El comando solo funciona con entornos development y staging. Con una credencial de producción se detiene antes de enviar cualquier solicitud y termina con el código 3:

Si el servidor rechaza la solicitud porque el entorno es de producción, la CLI imprime su respuesta de problema, code: test_feature_not_in_production, y también termina con el código 3.

Códigos de salida

Código Significado
0 Detenido con Ctrl-C.
1 Error del servidor o fallo de red hacia KeenAuth, o no se pudo determinar el tipo del entorno actual.
2 Error de uso: falta --forward-to, no es una URL local, o un filtro o intervalo no es válido. No se envió ninguna solicitud.
3 Una credencial de producción, una credencial ausente, o el servidor respondió 401 o 403.
4 El plan no incluye la función (403 con plan_feature_unavailable).