Devloop
Prueba los webhooks de Factuarea en local sin desplegar ni ngrok — factuarea listen reenvía los eventos de tu cuenta a localhost con un cuerpo firmado, factuarea trigger produce eventos reales en sandbox.
Prueba tus webhooks en local sin desplegar ni ngrok, al estilo del CLI de
Stripe. El bucle tiene dos mitades: listen reenvía los eventos de tu
cuenta a tu máquina, trigger produce eventos reales en sandbox para
reenviar.
Reenviar eventos a localhost
factuarea listen --forward-to http://localhost:3000/webhookslisten sondea el feed de eventos, reconstruye el cuerpo del webhook y lo firma
con HMAC (Factuarea-Signature) usando un secret efímero whsec_… que imprime
al arrancar. Configura ese secret en tu verificador y tu código de verificación
corre sin cambios — sin diferencias de código entre local y producción.
Por seguridad, listen solo reenvía a localhost. Para reenviar a un host
remoto, pasa --allow-remote-forward explícitamente.
Producir eventos para probar
En otra terminal, produce eventos reales en el sandbox:
factuarea trigger invoice.paid
factuarea trigger --list # eventos soportadostrigger solo opera en el sandbox — requiere una key fact_test_. Nunca
produce eventos contra datos de producción.
Por qué la verificación queda idéntica
El esquema de firma es el mismo que usa la plataforma, así que el verificador que despliegas a producción es el verificador con el que pruebas en local:
- HMAC-SHA256 sobre el cuerpo crudo con una comparación de tiempo constante.
- Una tolerancia de timestamp que rechaza los reenvíos.
- Ambas firmas aceptadas durante una ventana de gracia de rotación del secret.
La única diferencia es el secret: en local es el whsec_… efímero de listen;
en producción es el secret del endpoint. Consulta
Webhooks para el contrato de firma completo y los
verificadores de los SDKs.
Una fase futura sustituye el sondeo de listen por un relay WebSocket. La
superficie de comandos queda igual; solo cambia el transporte.
Uso
El árbol de comandos de factuarea — list, show, create, acciones de dominio, descargas binarias, subidas multipart, el escape hatch genérico api y el manifiesto commands --json.
Agentes y scripting
El contrato agent-first del CLI factuarea — JSON estable por stdout, errores estructurados por stderr, exit codes semánticos, el manifiesto commands --json, scope-check local y confirmación tipada de operaciones irreversibles.