Webhooks

Delivery model

The platform pushes document results and verification verdicts to your server so you do not need to poll.

• One callback URL per application, configured either in the console ("Webhook configuration" in the application details) or through Register webhook. Both write the same configuration and behave identically; the latest save wins, and the callback format and headers never depend on where the URL was configured. The console currently offers only the invoice.verify.completed subscription; subscribe to other events with eventos when registering. NF-e, NFC-e, CT-e, DC-e and NFS-e results and the NF-e verification verdict are all delivered to this URL.
• The callback token is optional. When one is set (entered in the console or sent at registration), every callback carries it verbatim in the token and x-token headers, whatever the event type; without one, neither header is sent. The console shows only a masked value, and the token can be changed or cleared there. Visible ASCII characters only (no spaces), up to 256.
• At-least-once delivery. A retry after a timeout can reach you even though the original attempt was processed, and the same event can be fanned out to several targets. Deduplicate on the event id (X-Tffiscal-Event-Id header, and event_id in enveloped payloads): it is identical across every attempt of the same event.
• Every delivery is an HTTP POST with a JSON body (Content-Type: application/json; charset=utf-8) to the registered URL.
• Test and production documents follow the same contract, signature and retry schedule, see Environments.

Event catalogue

Two payload shapes are used, chosen only by the event type (last column above) and never by whether the URL was configured in the console or through the registration endpoint:

• Document result object: a bare JSON object whose first field is tipo (NF-e / NFC-e / CT-e / DC-e / NFS-e), with a fixed field order. Used by the NF-e authorized and rejected results, by all five NFC-e events (nfce.*) and by the authorized, rejected and cancellation-related results of CT-e, DC-e and NFS-e. It has no event_id field; deduplicate on the X-Tffiscal-Event-Id header.
• Event envelope: { "version", "event_id", "event_type", "occurred_at", "data" }. Used by invoice.canceled, invoice.cce.registered, invoice.verify.completed, cte.event.registered, nfse.inbound.* and email.sent / email.failed. Fields inside data are only ever added, never renamed or removed; a breaking change bumps version.

Note: SEFAZ rejections are never HTTP errors of the issuance call. They surface as the query status Negada and as the invoice.rejected / cte.rejected / dce.rejected event. A CT-e task that fails terminally on the platform side (Falha) sends no callback; use the CT-e query to detect it.

Request headers

Verifying the signature

Compute HMAC-SHA256 over the string timestamp + "." + rawBody with your app_secret and compare it in constant time with the X-Tffiscal-Signature header. Use the raw received bytes: deserializing and re-serializing the payload first changes field order or whitespace and breaks the signature. Reject deliveries whose timestamp is too old (5 minutes is a reasonable tolerance).

Verifying the signature is recommended: it proves both the origin and that the body was not altered. If you set a callback token, you can also compare the token header with it.

Node.js:

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

/**
 * Verifies a TF Fiscal webhook delivery.
 * @param {string} secret your app_secret
 * @param {string} timestamp value of the X-Tffiscal-Timestamp header
 * @param {Buffer|string} rawBody the raw, unparsed request body
 * @param {string} signature value of the X-Tffiscal-Signature header
 * @returns {boolean} true when the signature is authentic
 */
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 {

    /**
     * Verifies a TF Fiscal webhook delivery.
     *
     * @param secret    your app_secret
     * @param timestamp value of the X-Tffiscal-Timestamp header
     * @param rawBody   the raw, unparsed request body
     * @param signature value of the X-Tffiscal-Signature header
     * @return true when the signature is authentic
     */
    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;
        }
    }
}

NF-e payload

Events invoice.authorized and invoice.rejected. Registered through Register webhook; see NF-e for the issuance flow.

Authorized:

{
  "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"
}

Denied:

{
  "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"
}

Fields without a value appear in the payload as empty values.

NF-e cancellation and correction letter

invoice.canceled uses the event envelope with data carrying invoice_id (the platform invoice identifier), chave (44-digit access key) and protocolo (cancellation event protocol). The cancellation itself is confirmed synchronously by Cancel NF-e and by the query status Cancelada.

invoice.cce.registered is reserved in the catalogue (data: invoice_id / chave / n_seq). The CC-e registration endpoint returns the protocol synchronously and no callback is delivered for it at present.

CT-e payload

Same registration and headers as NF-e; see CT-e for the issuance flow. The result object uses tipo = CT-e with a fixed field order.

Authorized:

{
  "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 and cteLinkXml are usable as soon as the authorization callback arrives; the links need no signature headers and redirect with 302, see File download.

Event registered (cte.event.registered), for example a delivery receipt (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"
  }
}

DC-e payload

Same registration and headers as NF-e; see DC-e for the issuance flow. The result object uses tipo = DC-e with 14 fields in fixed order.

Authorized:

{
  "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="
}

Rejected:

{
  "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
}

Failure before numbering (company not configured for DC-e, missing series, message mapping failure and other terminal failures where the document was never numbered and has no chave): dce.rejected is still delivered, the document fact fields are null, dceMotivoStatus carries the failure reason and dceDataEmissao the acceptance time. Correlate by dceId and never assume dceChaveAcesso is present:

{
  "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
}

Cancelled:

{
  "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
}

Cancellation rejected:

{
  "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="
}

Both links share the query API shape (/openapi/files/{kind}/{ref}?token=...) and their lifetime comes from the tenant-level setting (7 days by default), see File download.

NFC-e payload

Reuses the NF-e callback URL and headers; the issuance flow is in NFC-e. These five events are not part of the default subscription: list them in eventos when registering the webhook to have them delivered. The result object has the NF-e fields with tipo = NFC-e plus the QR code content in nfeQrCode; the 14 fields keep a fixed order and appear even when empty.

Authorized:

{
  "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"
}

Rejected:

{
  "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
}

NFS-e payload

Same registration and headers as NF-e; see NFS-e for the issuance flow. The result object uses tipo = NFS-e with a fixed field order.

Note: Subscription semantics. An app that has never registered any subscription row receives all six outbound events. As soon as any subscription row exists for the app (for example an inbound or invoice e-mail event), the app switches to allow-list mode and only explicitly enabled events are delivered. When subscribing to inbound events, enable the outbound events you need as well, otherwise outbound notifications stay parked waiting for a target.

Authorized:

{
  "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 is the moment of this state change. Delivery order is not guaranteed: retries and multiple instances can make an older event arrive after a newer one. Compare it with the timestamp you already hold and drop the older one instead of overwriting state in arrival order.

On a failure callback nfseChaveAcesso may be empty (the authority never generated a key); reconcile by nfseIdentificacaoDps then. A callback for a failure before numbering carries neither, so only nfseId can reconcile it.

The cancellation window and the review flow are described in Cancel NFS-e; inbound documents and manifestation in Inbound NFS-e.

Verification verdict payload

When Tier-2 SEFAZ verification settles, the platform POSTs invoice.verify.completed to your webhook URL. This is the only push channel for final verdicts; the chave lookup can serve as a polling fallback.

{
  "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)"
  }
}

Envelope:

data:

Webhook payloads carry only language-independent enum values; there are no *Description fields. Presentation text is up to the receiver.

Invoice e-mail payload

When an e-mail accepted by Send invoice e-mail reaches its terminal state, the platform sends email.sent (the mail service accepted the message) or email.failed (final failure). Both require an explicit subscription: they are only delivered when listed in eventos at Webhook registration. After either one the same document accepts a new send. The payload is the event envelope, with data fields in 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:

Failure example (São Paulo NFS-e whose wait for the key ran out):

{
  "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 means the mail service accepted the message, not that it reached the recipient inbox. Templates, attachments and states are in Invoice e-mail.

Retries and circuit breaker

• Any 2xx status acknowledges the delivery. Any other status, a network error or no response within 10 seconds counts as a failure.
• Failed deliveries are retried with backoff after the initial attempt:

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

• Five retries (six attempts in total, spanning about 8.6 hours). After that the platform can re-push the delivery manually on request.
• Circuit breaker: consecutive failed deliveries (10 by default) automatically disable the webhook. While it is disabled no new event is queued for it. Calling Register webhook again (or re-verifying and saving the URL in the console) restores delivery and resets the failure counter; ask the platform to replay events raised while the webhook was disabled.
• A re-registration takes effect on the next retry.

Receiver requirements

1. Return 2xx within 10 seconds. Best practice: persist the raw delivery, return 2xx immediately and process asynchronously.
2. Verify the origin: recompute the HMAC over the raw received bytes; if you set a callback token, also compare the token header with it.
3. Deduplicate on the event id (X-Tffiscal-Event-Id, or event_id in enveloped payloads).
4. Public URL: an absolute http / https URL reachable from the internet, at most 512 characters. Loopback, private and link-local addresses are rejected at registration.
5. Answer the test delivery: saving the URL in the console sends an event with X-Tffiscal-Event: webhook.verify (carrying token / x-token when a token is set); return 2xx without any business processing.
6. Gate business actions on the result fields (nfeStatus, cteStatus, dceStatus, nfseStatus, validationStatus), never on the synchronous API response alone.
7. Never assume optional fields are present: dceChaveAcesso can be null, reason only appears on failure, and empty NF-e fields arrive as empty values.

Troubleshooting