Webhooks

Modelo de entrega

La plataforma envía los resultados de los documentos y los veredictos de verificación a su servidor, sin necesidad de polling.

• Una URL de callback por aplicación, configurada en la consola ("Configuración de webhook" en los detalles de la aplicación) o mediante Registrar webhook. Ambas vías escriben la misma configuración y tienen el mismo efecto; prevalece el último guardado, y el formato y las cabeceras de los callbacks nunca dependen de dónde se configuró la URL. Hoy la consola solo ofrece la suscripción a invoice.verify.completed; suscríbase a los demás eventos con eventos al registrar. Los resultados de NF-e, NFC-e, CT-e, DC-e y NFS-e y el veredicto de la verificación de NF-e se entregan todos en esa URL.
• El token de callback es opcional. Cuando está definido (en la consola o en el registro), cada callback lo envía sin cambios en las cabeceras token y x-token, sea cual sea el tipo de evento; sin token, no se envía ninguna de las dos. La consola solo muestra el valor enmascarado, y allí se puede cambiar o borrar. Solo caracteres ASCII visibles (sin espacios), hasta 256.
• Entrega al menos una vez (at-least-once). Un reintento tras un timeout puede llegar aunque el intento original ya se haya procesado, y el mismo evento puede distribuirse a varios destinos. Deduplique por el id del evento (cabecera X-Tffiscal-Event-Id y, en los payloads con sobre, event_id): es idéntico en todos los intentos del mismo evento.
• Cada entrega es un HTTP POST con cuerpo JSON (Content-Type: application/json; charset=utf-8) a la URL registrada.
• Los documentos de prueba y de producción siguen el mismo contrato, la misma firma y el mismo calendario de reintentos, vea Entornos.

Catálogo de eventos

Se usan dos formas de payload, elegidas solo por el tipo de evento (última columna de arriba), nunca por si la URL se configuró en la consola o mediante el endpoint de registro:

• Objeto de resultado del documento: objeto JSON plano cuyo primer campo es tipo (NF-e / NFC-e / CT-e / DC-e / NFS-e), con orden fijo de campos. Lo usan los resultados de autorización y rechazo de la NF-e, los cinco eventos de la NFC-e (nfce.*) y los resultados de autorización, rechazo y cancelación de CT-e, DC-e y NFS-e. No tiene campo event_id; deduplique por la cabecera X-Tffiscal-Event-Id.
• Sobre de evento: { "version", "event_id", "event_type", "occurred_at", "data" }. Lo usan invoice.canceled, invoice.cce.registered, invoice.verify.completed, cte.event.registered, nfse.inbound.* y email.sent / email.failed. Los campos dentro de data solo se añaden, nunca se renombran ni se eliminan; un cambio incompatible incrementa version.

Nota: los rechazos de SEFAZ nunca son errores HTTP de la llamada de emisión. Aparecen como estado Negada en la consulta y como evento invoice.rejected / cte.rejected / dce.rejected. Una tarea de CT-e que falla de forma terminal del lado de la plataforma (Falha) no genera callback; use la consulta de CT-e para detectarla.

Cabeceras de la petición

Verificar la firma

Calcule HMAC-SHA256 sobre la cadena timestamp + "." + rawBody con su app_secret y compárelo en tiempo constante con la cabecera X-Tffiscal-Signature. Use los bytes crudos recibidos: deserializar y volver a serializar el payload cambia el orden de los campos o los espacios y rompe la firma. Rechace entregas con timestamp demasiado antiguo (5 minutos es una tolerancia razonable).

Se recomienda verificar la firma: prueba el origen y que el cuerpo no fue alterado. Si definió un token de callback, también puede comparar la cabecera token con él.

Node.js:

const crypto = require('node:crypto');

/**
 * Verifica una entrega de webhook de TF Fiscal.
 * @param {string} secret su app_secret
 * @param {string} timestamp valor de la cabecera X-Tffiscal-Timestamp
 * @param {Buffer|string} rawBody cuerpo crudo de la petición, sin parsear
 * @param {string} signature valor de la cabecera X-Tffiscal-Signature
 * @returns {boolean} true cuando la firma es auténtica
 */
function verifyWebhook(secret, timestamp, rawBody, signature) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(timestamp + '.' + rawBody, 'utf8')
    .digest('hex');
  return (
    expected.length === signature.length &&
    crypto.timingSafeEqual(Buffer.from(expected, 'utf8'), Buffer.from(signature, 'utf8'))
  );
}

Java:

import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public final class WebhookVerifier {

    /**
     * Verifica una entrega de webhook de TF Fiscal.
     *
     * @param secret    su app_secret
     * @param timestamp valor de la cabecera X-Tffiscal-Timestamp
     * @param rawBody   cuerpo crudo de la petición, sin parsear
     * @param signature valor de la cabecera X-Tffiscal-Signature
     * @return true cuando la firma es auténtica
     */
    public static boolean verify(String secret, String timestamp, String rawBody, String signature) {
        try {
            Mac mac = Mac.getInstance("HmacSHA256");
            mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
            byte[] digest = mac.doFinal((timestamp + "." + rawBody).getBytes(StandardCharsets.UTF_8));
            StringBuilder hex = new StringBuilder(digest.length * 2);
            for (byte b : digest) {
                hex.append(String.format("%02x", b));
            }
            return MessageDigest.isEqual(
                    hex.toString().getBytes(StandardCharsets.UTF_8),
                    signature.getBytes(StandardCharsets.UTF_8));
        } catch (Exception e) {
            return false;
        }
    }
}

Payload de NF-e

Eventos invoice.authorized e invoice.rejected. Se registran en Registrar webhook; vea NF-e para el flujo de emisión.

Autorizada:

{
  "tipo": "NF-e",
  "empresaId": "1934811222334455",
  "nfeId": "NFe-000014553",
  "nfeStatus": "Autorizada",
  "nfeLinkDanfe": "https://api.v2.tffiscal.com/openapi/files/danfe/35241204893402000113650010000117691017244265?token=MXw3fDEwMXwxNzU4...",
  "nfeLinkXml": "https://api.v2.tffiscal.com/openapi/files/xml/8801?token=MXw3fDEwMXwxNzU4...",
  "nfeNumero": "11769",
  "nfeSerie": "10",
  "nfeChaveAcesso": "35241204893402000113650010000117691017244265",
  "nfeDataEmissao": "2024-12-04T17:44:26Z",
  "nfeDataAutorizacao": "2024-12-04T17:44:26Z",
  "nfeNumeroProtocolo": "135240002599237"
}

Denegada:

{
  "tipo": "NF-e",
  "empresaId": "1934811222334455",
  "nfeId": "NFe-000014553",
  "nfeStatus": "Negada",
  "nfeMotivoStatus": "778 - Rejeicao: NCM inexistente",
  "nfeNumero": "11769",
  "nfeSerie": "10",
  "nfeChaveAcesso": "35241204893402000113650010000117691017244265",
  "nfeDataEmissao": "2024-12-04T17:44:26Z"
}

Los campos sin valor aparecen en el payload como valores vacíos.

Cancelación y carta de corrección de NF-e

invoice.canceled usa el sobre de evento con data trayendo invoice_id (identificador de la factura en la plataforma), chave (clave de acceso de 44 dígitos) y protocolo (protocolo del evento de cancelación). La cancelación en sí se confirma de forma síncrona en Cancelar NF-e y por el estado Cancelada en la consulta.

invoice.cce.registered está reservado en el catálogo (data: invoice_id / chave / n_seq). El endpoint de registro de la CC-e devuelve el protocolo de forma síncrona y por ahora no se entrega ningún callback para él.

Payload de CT-e

Mismo registro y mismas cabeceras que la NF-e; vea CT-e para el flujo de emisión. El objeto de resultado usa tipo = CT-e con orden fijo de campos.

Autorizado:

{
  "tipo": "CT-e",
  "empresaId": "1934811222334455",
  "cteId": "CTE-ORD-1",
  "cteStatus": "Autorizada",
  "cteMotivoStatus": null,
  "cteLinkDacte": "https://api.v2.tffiscal.com/openapi/files/dacte/3526...?token=...",
  "cteLinkXml": "https://api.v2.tffiscal.com/openapi/files/xml/7?token=...",
  "cteNumero": "1",
  "cteSerie": "1",
  "cteChaveAcesso": "3526...",
  "cteDataEmissao": "2026-09-06T12:00:00Z",
  "cteDataAutorizacao": "2026-09-06T12:00:03Z",
  "cteNumeroProtocolo": "135260000000001",
  "cteDigestValue": "..."
}

cteLinkDacte y cteLinkXml son utilizables en cuanto llega el callback de autorización; los enlaces no necesitan cabeceras de firma y redirigen con 302, vea Descarga de archivos.

Evento registrado (cte.event.registered), por ejemplo un comprobante de entrega (110180):

{
  "version": "1.0",
  "event_id": "987654321098765432",
  "event_type": "cte.event.registered",
  "occurred_at": "2026-09-06T13:00:00Z",
  "data": {
    "event_code": "110180",
    "n_seq": "1",
    "protocolo": "135260000000099"
  }
}

Payload de DC-e

Mismo registro y mismas cabeceras que la NF-e; vea DC-e para el flujo de emisión. El objeto de resultado usa tipo = DC-e con 14 campos en orden fijo.

Autorizada:

{
  "tipo": "DC-e",
  "empresaId": "1934811222334455",
  "dceId": "DCe-000012333",
  "dceStatus": "Autorizada",
  "dceMotivoStatus": null,
  "dceLinkDace": "https://api.v2.tffiscal.com/openapi/files/dace/35260940673061000134990010000000011100000016?token=...",
  "dceLinkXml": "https://api.v2.tffiscal.com/openapi/files/xml/7?token=...",
  "dceNumero": "1",
  "dceSerie": "1",
  "dceChaveAcesso": "41260940673061000134990010000000011101234565",
  "dceDataEmissao": "2026-09-06T12:00:00Z",
  "dceDataAutorizacao": "2026-09-06T12:00:03Z",
  "dceNumeroProtocolo": "141260000000001",
  "dceDigestValue": "tasG40Ic6Zh7PIBiLEEH7Hb940Y="
}

Rechazada:

{
  "tipo": "DC-e",
  "empresaId": "1934811222334455",
  "dceId": "DCe-000012333",
  "dceStatus": "Negada",
  "dceMotivoStatus": "225 - Rejeicao: Falha no schema XML",
  "dceLinkDace": null,
  "dceLinkXml": null,
  "dceNumero": "1",
  "dceSerie": "1",
  "dceChaveAcesso": "4126...",
  "dceDataEmissao": "2026-09-06T12:00:00Z",
  "dceDataAutorizacao": null,
  "dceNumeroProtocolo": null,
  "dceDigestValue": null
}

Fallo antes de la numeración (empresa no configurada para DC-e, serie ausente, fallo de mapeo del mensaje y otros fallos terminales en los que el documento nunca fue numerado y no tiene chave): dce.rejected se entrega igualmente, los campos de hecho del documento son null, dceMotivoStatus trae el motivo del fallo y dceDataEmissao el momento de aceptación. Correlacione por dceId y nunca suponga que dceChaveAcesso está presente:

{
  "tipo": "DC-e",
  "empresaId": "1934811222334455",
  "dceId": "DCe-000012333",
  "dceStatus": "Negada",
  "dceMotivoStatus": "Empresa não configurada para emissão de DC-e",
  "dceLinkDace": null,
  "dceLinkXml": null,
  "dceNumero": null,
  "dceSerie": null,
  "dceChaveAcesso": null,
  "dceDataEmissao": "2026-09-06T12:00:00Z",
  "dceDataAutorizacao": null,
  "dceNumeroProtocolo": null,
  "dceDigestValue": null
}

Cancelada:

{
  "tipo": "DC-e",
  "empresaId": "1934811222334455",
  "dceId": "DCe-000012333",
  "dceStatus": "Cancelada",
  "dceMotivoStatus": null,
  "dceLinkDace": "https://api.v2.tffiscal.com/openapi/files/dace/35260940673061000134990010000000011100000016?token=...",
  "dceLinkXml": "https://api.v2.tffiscal.com/openapi/files/xml/7?token=...",
  "dceNumero": "1",
  "dceSerie": "1",
  "dceChaveAcesso": "4126...",
  "dceDataEmissao": "2026-09-06T12:00:00Z",
  "dceDataAutorizacao": "2026-09-06T15:00:00Z",
  "dceNumeroProtocolo": "141260000000099",
  "dceDigestValue": null
}

Cancelación rechazada:

{
  "tipo": "DC-e",
  "empresaId": "1934811222334455",
  "dceId": "DCe-000012333",
  "dceStatus": "CancelamentoNegado",
  "dceMotivoStatus": "594 - Rejeicao: O numero de sequencia do evento informado e maior que o permitido",
  "dceLinkDace": null,
  "dceLinkXml": "https://api.v2.tffiscal.com/openapi/files/xml/7?token=...",
  "dceNumero": "1",
  "dceSerie": "1",
  "dceChaveAcesso": "4126...",
  "dceDataEmissao": "2026-09-06T12:00:00Z",
  "dceDataAutorizacao": null,
  "dceNumeroProtocolo": "141260000000001",
  "dceDigestValue": "tasG40Ic6Zh7PIBiLEEH7Hb940Y="
}

Ambos enlaces comparten la forma de la API de consulta (/openapi/files/{kind}/{ref}?token=...) y su vigencia viene de la configuración del tenant (7 días por defecto), vea Descarga de archivos.

Payload de NFC-e

Reutiliza la URL de callback y las cabeceras de la NF-e; el flujo de emisión está en NFC-e. Estos cinco eventos no forman parte de la suscripción por defecto: lístelos en eventos al registrar el webhook para que se entreguen. El objeto de resultado tiene los campos de la NF-e con tipo = NFC-e y el contenido del QR Code en nfeQrCode; los 14 campos tienen orden fijo y aparecen aunque estén vacíos.

Autorizada:

{
  "tipo": "NFC-e",
  "empresaId": "1934811222334455",
  "nfeId": "PDV01-000123",
  "nfeStatus": "Autorizada",
  "nfeMotivoStatus": null,
  "nfeLinkDanfe": "https://api.v2.tffiscal.com/openapi/files/danfce/35261111222333000181650010000001231123456780?token=MXw3fDEwMXwxNzU4...",
  "nfeLinkXml": "https://api.v2.tffiscal.com/openapi/files/xml/9901?token=MXw3fDEwMXwxNzU4...",
  "nfeNumero": "123",
  "nfeSerie": "1",
  "nfeChaveAcesso": "35261111222333000181650010000001231123456780",
  "nfeDataEmissao": "2026-11-04T15:20:01Z",
  "nfeDataAutorizacao": "2026-11-04T15:20:02Z",
  "nfeNumeroProtocolo": "135261234567890",
  "nfeQrCode": "https://www.homologacao.nfce.fazenda.sp.gov.br/qrcode?p=35261111222333000181650010000001231123456780|3|2"
}

Rechazada:

{
  "tipo": "NFC-e",
  "empresaId": "1934811222334455",
  "nfeId": "PDV01-000123",
  "nfeStatus": "Negada",
  "nfeMotivoStatus": "725 - Rejeicao: NFC-e com CFOP invalido",
  "nfeLinkDanfe": null,
  "nfeLinkXml": null,
  "nfeNumero": "123",
  "nfeSerie": "1",
  "nfeChaveAcesso": "35261111222333000181650010000001231123456780",
  "nfeDataEmissao": "2026-11-04T15:20:01Z",
  "nfeDataAutorizacao": null,
  "nfeNumeroProtocolo": null,
  "nfeQrCode": null
}

Payload de NFS-e

Mismo registro y mismas cabeceras que NF-e; vea NFS-e para el flujo de emisión. El objeto de resultado usa tipo = NFS-e, con orden fijo de campos.

Aviso: Semántica de las suscripciones. Una aplicación que nunca registró ninguna fila de suscripción recibe los seis eventos de salida. En cuanto exista cualquier fila de suscripción para la aplicación (por ejemplo un evento de entrada o de e-mail de facturas), pasa al modo lista de permitidos y solo se entregan los eventos habilitados explícitamente. Al suscribirse a eventos de entrada, habilite también los eventos de salida que necesite, o las notificaciones de salida quedarán en espera de destinatario.

Autorizada:

{
  "tipo": "NFS-e",
  "empresaId": "1001",
  "nfseId": "PED-20260918-001",
  "nfseStatus": "Autorizada",
  "nfseMotivoStatus": null,
  "nfseLinkDanfse": "https://api.v2.tffiscal.com/openapi/files/danfse/…",
  "nfseLinkXml": "https://api.v2.tffiscal.com/openapi/files/xml/9001?token=…",
  "nfseNumero": "1287",
  "nfseSerie": "1",
  "nfseChaveAcesso": "3550308…",
  "nfseIdentificacaoDps": "DPS3550308…",
  "nfseDataEmissao": "2026-09-18T13:00:00Z",
  "nfseDataAutorizacao": "2026-09-18T13:00:03Z",
  "nfseNumeroProtocolo": null,
  "nfseAtualizadoEm": "2026-09-18T13:00:03Z"
}

nfseAtualizadoEm es el momento de este cambio de estado. El orden de entrega no está garantizado: los reintentos y las múltiples instancias pueden hacer que un evento antiguo llegue después de uno nuevo. Compárelo con la marca de tiempo que ya tiene y descarte el más antiguo en vez de sobrescribir el estado por orden de llegada.

En un callback de fallo el nfseChaveAcesso puede venir vacío (la autoridad nunca generó la clave); concilie por nfseIdentificacaoDps en ese caso. Un callback de fallo anterior a la numeración no trae ninguno de los dos, y solo el nfseId concilia.

La ventana de cancelación y el flujo de análisis están en Cancelar NFS-e; las facturas recibidas y la manifestación, en NFS-e recibidas.

Payload del veredicto de verificación

Cuando la verificación de nivel 2 en SEFAZ se resuelve, la plataforma envía invoice.verify.completed a su URL de webhook. Este es el único canal push para veredictos finales; la consulta por chave puede servir como respaldo por polling.

{
  "version": "1.0",
  "event_id": "1950000000000001",
  "event_type": "invoice.verify.completed",
  "occurred_at": "2026-07-23T17:16:23Z",
  "data": {
    "chaveAcesso": "35260764962869000108550990001366171195929648",
    "validationStatus": "VALIDATED",
    "status": "Autorizada",
    "cStat": "100",
    "xMotivo": "Autorizado o uso da NF-e",
    "protocolo": { "numero": "135262955451772", "digestValue": "oAEE...HwY=" },
    "dataAutorizacao": "2026-07-23T14:30:09Z",
    "eventos": [],
    "verifiedAt": "2026-07-23T17:16:23Z",
    "reason": "present only for REJECTED / VALIDATION_ERROR (stable English text)"
  }
}

Sobre:

data:

Los payloads de webhook solo traen valores de enumeración independientes del idioma; no hay campos *Description. El texto de presentación queda a cargo del receptor.

Payload del e-mail de facturas

Cuando un correo aceptado en Enviar correo de la factura llega a su estado terminal, la plataforma envía email.sent (el servicio de envío aceptó el mensaje) o email.failed (fallo definitivo). Ambos requieren suscripción explícita: solo se entregan si están en eventos en el registro del webhook. Tras cualquiera de ellos el mismo documento acepta un nuevo envío. El payload es el sobre de evento, con los campos de data en snake_case.

{
  "version": "1.0",
  "event_id": "1950000000000006",
  "event_type": "email.sent",
  "occurred_at": "2026-09-28T12:00:31Z",
  "data": {
    "email_id": "2103160000000000001",
    "id": "email-pedido-8842-1",
    "tipo_documento": "NFe",
    "documento_id": "pedido-8842",
    "chave": "35241204893402000113650010000117691017244265",
    "destinatarios": ["comprador@exemplo.com"],
    "status": "Enviado",
    "motivo_falha": null
  }
}

data:

Ejemplo de fallo (NFS-e de São Paulo cuya espera por la clave se agotó):

{
  "version": "1.0",
  "event_id": "1950000000000007",
  "event_type": "email.failed",
  "occurred_at": "2026-09-28T14:00:30Z",
  "data": {
    "email_id": "2103160000000000002",
    "id": "mail-sp-000045",
    "tipo_documento": "NFSe",
    "documento_id": "SP-20260928-045",
    "chave": null,
    "destinatarios": ["financeiro@cliente.com.br"],
    "status": "Falha",
    "motivo_falha": "等待超时：chaveAcesso"
  }
}

email.sent significa que el servicio de envío aceptó el mensaje, no que llegó a la bandeja del destinatario. Plantillas, adjuntos y estados están en E-mail de facturas.

Reintentos y circuit breaker

• Cualquier estado 2xx confirma la entrega. Cualquier otro estado, un error de red o la falta de respuesta en 10 segundos cuenta como fallo.
• Las entregas fallidas se reintentan con backoff tras el intento inicial:

1 min, 5 min, 30 min, 2 h, 6 h

• Cinco reintentos (seis intentos en total, en unas 8,6 horas). Después, la plataforma puede reenviar la entrega manualmente a petición.
• Circuit breaker: los fallos de entrega consecutivos (10 por defecto) desactivan automáticamente el webhook. Mientras está desactivado no se encola ningún evento nuevo para él. Llamar de nuevo a Registrar webhook (o revalidar y guardar la URL en la consola) restaura la entrega y pone a cero el contador de fallos; pida a la plataforma el reenvío de los eventos generados mientras el webhook estaba desactivado.
• Un nuevo registro surte efecto en el siguiente reintento.

Requisitos del receptor

1. Responda 2xx en menos de 10 segundos. Buena práctica: persista la entrega cruda, responda 2xx de inmediato y procese de forma asíncrona.
2. Verifique el origen: recalcule el HMAC sobre los bytes crudos recibidos; si definió un token de callback, compare también la cabecera token con él.
3. Deduplique por el id del evento (X-Tffiscal-Event-Id o event_id en los payloads con sobre).
4. URL pública: una URL absoluta http / https accesible desde internet, de como máximo 512 caracteres. Las direcciones de loopback, privadas y link-local se rechazan en el registro.
5. Responda a la entrega de prueba: guardar la URL en la consola envía un evento con X-Tffiscal-Event: webhook.verify (con token / x-token cuando hay token definido); responda 2xx sin ningún procesamiento de negocio.
6. Condicione las acciones de negocio a los campos de resultado (nfeStatus, cteStatus, dceStatus, nfseStatus, validationStatus), nunca solo a la respuesta síncrona de la API.
7. Nunca suponga que los campos opcionales están presentes: dceChaveAcesso puede ser null, reason solo aparece en fallo y los campos vacíos de NF-e llegan como valores vacíos.

Solución de problemas