Recorrido local con túnel
Probar webhooks en tu equipo con un túnel HTTPS temporal y el ensayo automatizado desechable.
Los destinos exigen HTTPS público, así que para probar en tu equipo expón el receptor con un túnel: ngrok o Cloudflare Quick Tunnel. La URL temporal cambia cada vez que reinicias el túnel. No necesitas exponer la API ni la base de datos.
El recorrido paso a paso está en el recorrido rápido. Resumen:
npm run dev:webhooks
WEBHOOK_PUBLIC_KEY_FILE="$PWD/.local/webhooks/public.pem" npm run start:api
npm run start:worker
npm run start:webhooks
cloudflared tunnel --url http://127.0.0.1:3082
node dist/backend/examples/webhook-register.js register .local/credentials.json .local/webhook-receiver.json receiver-register-001 https://TU-TUNEL/webhooks/trifaco
node dist/backend/examples/webhook-receiver.js .local/webhook-receiver.json .local/webhook-inbox
node dist/backend/examples/webhook-register.js activate .local/credentials.json .local/webhook-receiver.json receiver-activate-001
node dist/backend/examples/webhook-pilot.js .local/credentials.json .local/invoice-webhook.json invoice-webhook-001Cada comando corre en su propia terminal hasta el túnel y el receptor. El receptor usa el puerto 3082; cámbialo con WEBHOOK_RECEIVER_PORT.
Problemas frecuentes
| Síntoma | Causa y solución |
|---|---|
Crear el destino falla con WEBHOOK_NOT_CONFIGURED | La API arrancó sin WEBHOOK_PUBLIC_KEY_FILE. Reiníciala con la variable. |
dev:webhooks falla | Ya existen claves en .local/webhooks. Reutilízalas; no las regeneres. |
register falla con EEXIST | Ya existe .local/webhook-receiver.json. Si el destino ya existe, consúltalo y rota su secreto. |
| Los intentos fallan por DNS | Tu DNS filtra los dominios temporales. El operador puede configurar WEBHOOK_DNS_SERVERS=1.1.1.1,8.8.8.8 en la API y en el worker. No cambia el DNS del sistema ni omite las comprobaciones de direcciones. |
| El piloto agota la espera | ¿Reutilizaste una factura ya admitida antes de activar el destino? Su aviso es anterior al destino: usa una copia nueva. Si no, conserva el documento y la clave, y consulta el documento y sus intentos. No emitas otra factura. |
Si el registro falla después de enviar, el archivo de configuración puede quedar vacío: consulta el destino y rota su secreto antes de continuar.
Ensayo automatizado desechable
npm run build
TEST_WEBHOOK_DNS_SERVERS=1.1.1.1,8.8.8.8 TEST_WEBHOOK_TUNNEL_BIN=/ruta/al/cloudflared node scripts/test-integration-isolated.mjs webhook-tunnelUsa un PostgreSQL aislado, una empresa sintética, un receptor temporal y el transporte HTTPS real. Cierra el túnel al terminar. Sin TEST_WEBHOOK_TUNNEL_BIN, el caso se omite, por eso no corre en CI. No mide latencia ni capacidad.
Evidencia del diseño y del despliegue: TRIF-26.