Webhooks

Un webhook es una dirección de su servidor a la que Fiscalisto manda un evento cada vez que cambia un comprobante de su cuenta. Con ellos su sistema se entera de lo que no pasa en la respuesta de una solicitud: una cancelación que el cliente acepta días después, una factura que el PAC tardó en timbrar o un lote que terminó.

Tipos de eventoCopiar enlace a esta sección

Son todos los que hay. Cada uno trae en data.object el objeto completo, igual que su GET, con el estado que tenía cuando pasó. Abra uno para ver el evento entero tal como llega, campo por campo.

Lo que no manda evento: crear o cambiar clientes, productos, emisores y webhooks (eso lo hace su sistema y ya tiene la respuesta), y los envíos por correo.

{
  "id": "evt_0PKhIdhYuAGwzmMQYfkc",
  "object": "event",
  "type": "invoice.stamped",
  "api_version": "2026-10-24",
  "livemode": false,
  "created_at": "2026-10-24T10:15:42-06:00",
  "data": {
    "object": { "id": "inv_OufpKqnrvx9p28SINJVjjWKYRhojBTJb8P", "object": "invoice", "status": "valid", "...": "..." }
  }
}

La página de cada evento (en la tabla de arriba) tiene un ejemplo completo de lo que manda, y GET /v1/events devuelve los de los últimos 30 días.

Agregar un webhookCopiar enlace a esta sección

Cada url va en un solo endpoint por modo, para que ningún evento llegue dos veces: crear otro con la misma contesta 400 endpoint_exists con el id del que ya la tiene, para cambiarlo con POST /v1/webhook_endpoints/{id}.

curl https://api.fiscalisto.com/v1/webhook_endpoints \
  -H "Authorization: Bearer $FISCALISTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://mi-plataforma.mx/webhooks/fiscalisto",
    "events": ["invoice.stamped", "invoice.failed", "invoice.canceled"]
  }'

La respuesta trae el secret (whsec_…) una sola vez: guárdelo en su servidor. Sin events recibe todos. También puede agregarlo en Desarrolladores › Webhooks. Cada modo tiene sus propios webhooks: uno creado con una llave fk_test_ solo recibe eventos de pruebas.

La dirección debe ser https y pública. No se siguen redirecciones: use la dirección final. Para probar en su computadora no hace falta un túnel: npx fiscalisto listen --forward-to http://localhost:3000/webhooks/fiscalisto le reenvía los eventos de su cuenta de pruebas firmados igual que los de verdad, y npx fiscalisto trigger invoice.stamped provoca uno (vea CLI). Si prefiere registrar un endpoint de verdad, abra un túnel (cloudflared tunnel --url http://localhost:3000 o ngrok http 3000) y registre la dirección https que le da.

Verificar la firmaCopiar enlace a esta sección

Cada evento llega como POST con tres encabezados, según Standard Webhooks:

Verifique siempre la firma antes de confiar en el evento: cualquiera puede mandar un POST a su dirección. Con los SDKs es una línea y no necesita la llave de la API: verifyWebhook(cuerpo, encabezados, secreto) en TypeScript, verify_webhook(…) en Python, Webhook::verify(…) en PHP, fiscalisto.VerifyWebhook(…) en Go, Webhooks.verify(…) en Java y FiscalistoClient.Webhooks.Verify(…) en C#. En otro lenguaje, la librería standardwebhooks hace lo mismo (Ruby, Rust y los demás).

import express from "express";
import { verifyWebhook } from "fiscalisto";

const app = express();

// El cuerpo tal como llegó, sin convertirlo a JSON: la firma es de esos bytes.
app.post("/webhooks/fiscalisto", express.raw({ type: "application/json" }), async (req, res) => {
  let event;
  try {
    event = await verifyWebhook(req.body, req.headers, process.env.FISCALISTO_WEBHOOK_SECRET);
  } catch {
    return res.status(400).send("Firma inválida");
  }
  res.sendStatus(200); // Responda rápido; procese después.
  procesar(event);
});

import os
from flask import Flask, request
from fiscalisto import FiscalistoWebhookError, verify_webhook

app = Flask(__name__)

@app.post("/webhooks/fiscalisto")
def fiscalisto():
    try:
        event = verify_webhook(
            request.get_data(), request.headers, os.environ["FISCALISTO_WEBHOOK_SECRET"]
        )
    except FiscalistoWebhookError:
        return "Firma inválida", 400
    procesar(event)
    return "", 200

Sin libreríaCopiar enlace a esta sección

La firma es el HMAC-SHA256 de {webhook-id}.{webhook-timestamp}.{cuerpo} con su secreto sin el prefijo whsec_, decodificado de base64:

import base64, hashlib, hmac, json, time

def verificar(secreto, headers, cuerpo: bytes):
    msg_id = headers["webhook-id"]
    timestamp = headers["webhook-timestamp"]
    if abs(time.time() - int(timestamp)) > 300:
        raise ValueError("Evento viejo: puede ser una repetición maliciosa")
    llave = base64.b64decode(secreto.removeprefix("whsec_"))
    firmado = f"{msg_id}.{timestamp}.".encode() + cuerpo
    esperada = base64.b64encode(hmac.new(llave, firmado, hashlib.sha256).digest()).decode()
    for firma in headers["webhook-signature"].split(" "):
        version, _, valor = firma.partition(",")
        if version == "v1" and hmac.compare_digest(valor, esperada):
            return json.loads(cuerpo)
    raise ValueError("Firma inválida")

Rechace los eventos con más de 5 minutos de diferencia en webhook-timestamp: así nadie puede repetirle uno viejo.

Probar sus webhooksCopiar enlace a esta sección

Con una llave fk_test_ todo pasa en pruebas y sus webhooks de pruebas reciben los eventos de verdad:

1. Agregue un webhook de pruebas con la dirección de su túnel (vea arriba).
2. Timbre una factura con su llave de pruebas: con curl, con un SDK o con Probar en la referencia. Le llega invoice.stamped.
3. Para invoice.failed, timbre a uno de los RFC de prueba, como NOM010101FK9; para invoice.canceled, cancele la factura con "motive": "02".
4. En Desarrolladores › Webhooks vea cada entrega con lo que contestó su servidor, y reenvíela cuantas veces quiera mientras corrige su código. Desarrolladores › Eventos tiene todos los eventos, con lo que se mandó y cada entrega.

Un evento de prueba, sin timbrarCopiar enlace a esta sección

Para probar su código con cualquier evento, mande uno de prueba a su webhook. Le llega en ese momento, una sola vez, firmado como los reales, con un objeto de ejemplo (sus id no existen), aunque el webhook no escuche ese tipo:

curl https://api.fiscalisto.com/v1/webhook_endpoints/whe_8Kq2ZtR4mNw1Lp0sXc7V/test \
  -H "Authorization: Bearer $FISCALISTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "invoice.failed" }'

La respuesta trae el evento que se mandó y lo que contestó su servidor:

{
  "object": "webhook_test",
  "event": { "id": "evt_0PKhIdhYuAGwzmMQYfkc", "object": "event", "type": "invoice.failed", "...": "..." },
  "delivery": { "ok": true, "status": 200, "error": null, "response_body": "{\"received\":true}", "duration_ms": 182 }
}

Sin type manda invoice.stamped. En el panel es Mandar evento de prueba, en cada webhook. El evento de prueba no sale en GET /v1/events, pero sí en las entregas del webhook, y puede reenviarlo.

ResponderCopiar enlace a esta sección

• Conteste un código 2xx en menos de 15 segundos. Cualquier otro código, una redirección o no contestar a tiempo cuenta como falla.
• Conteste primero y procese después (en una cola o en segundo plano), para no pasar de los 15 segundos.
• Un evento puede llegar más de una vez. Guarde el webhook-id de los que ya procesó e ignore los repetidos.
• Los eventos pueden llegar en otro orden. Para saber el estado actual de un comprobante use el status del objeto que trae el evento o consúltelo con GET.

ReintentosCopiar enlace a esta sección

Si su servidor falla, reintentamos el mismo evento durante un día: a los 5 segundos, 5 minutos, 30 minutos, 2 horas, 5 horas, 10 horas y 10 horas. Cada intento trae el mismo webhook-id y un webhook-timestamp nuevo.

Un webhook que falla todos los reintentos queda en status: "failing". Si sigue así 5 días, se apaga ("disabled") y deja de recibir eventos; vuelva a encenderlo con POST /v1/webhook_endpoints/{id} y "disabled": false, o en el panel. En Desarrolladores › Webhooks cada webhook muestra sus últimos 7 días (entregados, fallidos, tasa de error y respuesta promedio) y sus entregas con lo que contestó su servidor, y puede reenviar cualquiera. Reenviar es un intento aparte, ahora: no cambia los reintentos automáticos, y si llega, ya no se reintenta.

Si se le pasaron eventos, GET /v1/events tiene los de los últimos 30 días; filtre por type (uno, o todos los de un recurso con un comodín: invoice.*), por object (el id del comprobante) o con delivery_success=false por los que algún webhook no recibió:

curl "https://api.fiscalisto.com/v1/events?type=invoice.*&delivery_success=false" \
  -H "Authorization: Bearer $FISCALISTO_API_KEY"

Cambiar el secretoCopiar enlace a esta sección

POST /v1/webhook_endpoints/{id}/roll_secret le da un secreto nuevo. El anterior sigue firmando 24 horas: mientras tanto cada evento trae dos firmas, una con cada secreto, y la verificación pasa con cualquiera. Cambie su servidor al nuevo dentro de ese plazo. Para otro plazo mande previous_secret_expires_in en segundos; si el secreto se filtró, mande 0 y el anterior deja de firmar en ese momento.

curl -X POST https://api.fiscalisto.com/v1/webhook_endpoints/whe_0q1Vmmw52sbDpmtsKD1E/roll_secret \
  -H "Authorization: Bearer $FISCALISTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "previous_secret_expires_in": 0 }'