Probar webhooks en local

Con el CLI fiscalapi recibes en tu computadora los eventos de tu cuenta, disparas eventos de prueba y reenvías los que te faltaron, sin exponer tu servidor a internet.

Cómo funciona

1. fiscalapi listen abre tu escucha de CLI: un webhook sin URL, uno por persona, con su propio secreto de firma.
2. Cuando ocurre un evento en tu cuenta, o cuando lo disparas, el servidor de Fiscalapi lo genera, lo firma con el secreto de tu escucha y crea una entrega para ella.
3. El CLI toma la entrega y la reenvía a tu servidor local como un POST con el cuerpo exacto y los headers firmados.
4. Tu servidor verifica la firma y responde, igual que con un webhook de URL.

Tu computadora no genera los eventos ni necesita una URL pública: el CLI pide las entregas a Fiscalapi y las reenvía a localhost.

Instalar el CLI

fiscalapi es un solo binario para Windows, Linux y macOS; no necesitas instalar .NET. Descarga el empaque de tu sistema y el archivo SHA256SUMS desde GitHub Releases, y verifica el SHA-256 antes de ejecutarlo.

base=https://github.com/FiscalAPI/fiscalapi-cli/releases/latest/download
curl -fsSLO "$base/fiscalapi-linux-x64.tar.gz"
curl -fsSLO "$base/SHA256SUMS"
grep ' fiscalapi-linux-x64.tar.gz$' SHA256SUMS | sha256sum -c -   # debe decir: OK
tar -xzf fiscalapi-linux-x64.tar.gz
sudo install -m 0755 fiscalapi /usr/local/bin/fiscalapi
fiscalapi --version

package=fiscalapi-osx-arm64.tar.gz   # en una Mac Intel: fiscalapi-osx-x64.tar.gz
base=https://github.com/FiscalAPI/fiscalapi-cli/releases/latest/download
curl -fsSLO "$base/$package"
curl -fsSLO "$base/SHA256SUMS"
grep " $package\$" SHA256SUMS | shasum -a 256 -c -   # debe decir: OK
tar -xzf "$package"
sudo mkdir -p /usr/local/bin
sudo install -m 0755 fiscalapi /usr/local/bin/fiscalapi
fiscalapi --version

$base = 'https://github.com/FiscalAPI/fiscalapi-cli/releases/latest/download'
Invoke-WebRequest "$base/fiscalapi-win-x64.zip" -OutFile fiscalapi-win-x64.zip
Invoke-WebRequest "$base/SHA256SUMS" -OutFile SHA256SUMS
$expected = (Select-String -Path SHA256SUMS -Pattern ' fiscalapi-win-x64\.zip$').Line.Split(' ')[0]
$actual = (Get-FileHash fiscalapi-win-x64.zip -Algorithm SHA256).Hash.ToLowerInvariant()
if ($actual -ne $expected) { throw "El SHA-256 no coincide: $actual" } else { 'SHA-256 OK' }

$dir = Join-Path $env:LOCALAPPDATA 'Programs\fiscalapi'
Expand-Archive fiscalapi-win-x64.zip -DestinationPath $dir -Force

La verificación debe decir OK. Si dice FAILED o no coincide, borra lo que descargaste y vuelve a bajarlo.

Estos comandos instalan la última versión publicada. Para una versión fija, cambia releases/latest/download por releases/download/v0.1.0.

Cómo agregar el CLI al PATH en Windows, qué hacer si Gatekeeper o SmartScreen lo bloquean, cómo actualizarlo y cómo desinstalarlo está en el repositorio del CLI.

Iniciar sesión

$ fiscalapi login
API key:
Tenant key:
Listo. Credenciales guardadas para test.fiscalapi.com.

El comando pide tu API key y tu tenant key sin mostrarlas, las valida con la API y las guarda en el almacén de credenciales de tu sistema. Trabaja en el ambiente de pruebas por omisión; para producción usa fiscalapi login --live. Obtén tus llaves en Obtener credenciales.

La API key necesita el permiso Webhooks.Manage. Sin él, listen, trigger y los comandos de webhooks responden 403, y login te lo advierte al guardar las llaves.

En Linux sin almacén de credenciales (WSL, un servidor sin escritorio o un contenedor), login termina con "No hay un almacén de credenciales disponible en este sistema." En ese caso define las variables de entorno FISCALAPI_API_KEY y FISCALAPI_TENANT_KEY, las dos juntas, y no uses login.

Recibir eventos en tu servidor local

$ fiscalapi listen --forward-to http://localhost:3000/webhooks
Listo. Tu secreto de firma es whsec_… (escucha 9b2e7c4a-1d3f-4e6b-8a5c-0f1e2d3c4b5a)
2026-10-12 09:47:46  --> invoice.canceled [3f9c1d2e-7b4a-4e8f-9a1b-2c3d4e5f6a7b] [200]

Cambia la URL por la ruta de tu servidor que recibe los webhooks. Cada línea trae la hora local, el tipo, el id del evento (el header webhook-id) y lo que respondió tu servidor:

listen corre hasta que lo detienes con Ctrl+C.

Verificar las entregas

Configura tu servidor con el secreto whsec_… que imprime listen y verifica cada entrega como cualquier otra, sobre el cuerpo crudo: Verificar la firma. Es el secreto de tu escucha de CLI, distinto del de tus webhooks de URL y estable entre reinicios, así que lo configuras una vez.

Para llevarlo a una variable de entorno sin copiarlo de la terminal:

export FISCALAPI_WEBHOOK_SECRET=$(fiscalapi listen --print-secret)

Con --print-secret, el CLI abre una sesión igual que listen. Córrelo antes de arrancar listen, no mientras corre.

Disparar un evento de prueba

Con listen abierto, dispara un evento desde otra terminal:

$ fiscalapi trigger invoice.canceled
Evento disparado: 3f9c1d2e-7b4a-4e8f-9a1b-2c3d4e5f6a7b al webhook 9b2e7c4a-1d3f-4e6b-8a5c-0f1e2d3c4b5a.

El evento tiene la forma y la firma de uno real de su tipo, y llega solo a tu escucha aunque su tipo no esté en tus --events. Puedes disparar cualquier tipo de evento salvo webhook.test.

Solo funciona en el ambiente de pruebas: con --live responde 403 con el detalle "fiscalapi trigger no está disponible en producción; usa el ambiente de pruebas." Sin --webhook ni un listen abierto, responde 409.

Reenviar un evento

Busca el evento con fiscalapi events list y reenvíalo a tu escucha:

$ fiscalapi events resend 3f9c1d2e-7b4a-4e8f-9a1b-2c3d4e5f6a7b
Reenvío creado: entrega d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a al webhook 9b2e7c4a-1d3f-4e6b-8a5c-0f1e2d3c4b5a.

Sin --webhook, el reenvío va a tu escucha y necesita un listen abierto; si no, responde 409. Llega con el mismo webhook-id y el mismo cuerpo, así que tu deduplicación lo reconoce.

Lo que conviene saber

Referencia del CLI

fiscalapi --help y fiscalapi <comando> --help describen cada opción. La referencia completa, con la salida en JSON, los códigos de salida y la solución de problemas, está en el repositorio del CLI.