Webhooks

Recibe notificaciones push cuando ocurren eventos en tu cuenta. Sin polling.

Como funcionan

Cuando un evento ocurre (factura timbrada, cancelacion aceptada, etc.), FiscaFacil envia un POST HTTP a la URL que configures con los datos del evento.

Eventos disponibles

factura.timbradaFactura timbrada exitosamente

factura.canceladaFactura cancelada ante el SAT

factura.cancelacion_pendienteCancelacion requiere aceptacion del receptor

factura.cancelacion_aceptadaReceptor acepto la cancelacion

factura.cancelacion_rechazadaReceptor rechazo la cancelacion

nomina.calculadaNomina de periodo calculada

nomina.calculadaNomina de periodo calculada exitosamente

nomina.recibo_timbradoRecibo de nomina timbrado (incluye UUID y xmlUrl)

nomina.sua_generadoArchivo SUA pagos.pro generado

nomina.sipare_exitosoLinea de captura obtenida de SIPARE

timbres.saldo_bajoSaldo de timbres por debajo del umbral

certificado.por_expirarCSD por expirar (30 dias antes)

Payload de ejemplo

POST https://tu-servidor.com/webhooks/fiscafacil
Content-Type: application/json
X-FiscaFacil-Signature: sha256=a1b2c3...

{
  "id": "evt_abc123",
  "type": "factura.timbrada",
  "created": "2026-03-21T12:00:00Z",
  "data": {
    "cfdiId": "clx...",
    "uuid": "6128396c-...",
    "total": 5800.00,
    "serie": "A",
    "folio": "42"
  }
}

Verificar firma

Cada webhook incluye un header X-FiscaFacil-Signature con un HMAC SHA-256 del body usando tu webhook secret. Siempre verifica la firma antes de procesar el evento.

import crypto from "crypto"

function verifyWebhook(body: string, signature: string, secret: string) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex")
  return signature === `sha256=${expected}`
}

Reintentos

Si tu servidor no responde con un 2xx en 10 segundos, FiscaFacil reintenta hasta 5 veces con backoff exponencial (1min, 5min, 30min, 2hrs, 24hrs).