Devloop
Prova els webhooks de Factuarea en local sense desplegar ni ngrok — factuarea listen reenvia els esdeveniments del teu compte a localhost amb un cos signat, factuarea trigger produeix esdeveniments reals en sandbox.
Prova els teus webhooks en local sense desplegar ni ngrok, a l'estil del CLI de
Stripe. El bucle té dues meitats: listen reenvia els esdeveniments del teu
compte a la teva màquina, trigger produeix esdeveniments reals en sandbox
per reenviar.
Reenviar esdeveniments a localhost
factuarea listen --forward-to http://localhost:3000/webhookslisten sondeja el feed d'esdeveniments, reconstrueix el cos del webhook i el
signa amb HMAC (Factuarea-Signature) fent servir un secret efímer whsec_…
que imprimeix en arrencar. Configura aquest secret al teu verificador i el teu
codi de verificació corre sense canvis — sense diferències de codi entre local i
producció.
Per seguretat, listen només reenvia a localhost. Per reenviar a un host
remot, passa --allow-remote-forward explícitament.
Produir esdeveniments per provar
En una altra terminal, produeix esdeveniments reals al sandbox:
factuarea trigger invoice.paid
factuarea trigger --list # esdeveniments suportatstrigger només opera al sandbox — requereix una key fact_test_. Mai
produeix esdeveniments contra dades de producció.
Per què la verificació queda idèntica
L'esquema de signatura és el mateix que fa servir la plataforma, així que el verificador que desplegues a producció és el verificador amb el qual proves en local:
- HMAC-SHA256 sobre el cos cru amb una comparació de temps constant.
- Una tolerància de timestamp que rebutja els reenviaments.
- Ambdues signatures acceptades durant una finestra de gràcia de rotació del secret.
L'única diferència és el secret: en local és el whsec_… efímer de listen; en
producció és el secret de l'endpoint. Consulta Webhooks per
al contracte de signatura complet i els verificadors dels SDKs.
Una fase futura substitueix el sondeig de listen per un relay WebSocket. La
superfície de comandes queda igual; només canvia el transport.
Ús
L'arbre de comandes de factuarea — list, show, create, accions de domini, descàrregues binàries, pujades multipart, l'escape hatch genèric api i el manifest commands --json.
Agents i scripting
El contracte agent-first del CLI factuarea — JSON estable per stdout, errors estructurats per stderr, exit codes semàntics, el manifest commands --json, scope-check local i confirmació tipada d'operacions irreversibles.