Webhooks

Webhooks são URLs HTTP do seu servidor que o Brasil NFe chama automaticamente quando algo acontece nas suas notas. Em vez de você ficar consultando a API em loop, é o Brasil NFe que avisa você — enviando um POST com o payload em JSON.

Use webhooks para integrar com ERP, sistema de logística, CRM, dashboards internos ou qualquer coisa que precise reagir a eventos fiscais em tempo (quase) real.

Cadastro pelo painel

O cadastro é feito em api.brasilnfe.com.br → Painel → Webhooks:

1. Clique em Adicionar webhook.
2. Informe um nome (ex.: "Integração ERP") e a URL que vai receber os POSTs (precisa ser HTTPS em produção).
3. Salve. O secret é gerado uma única vez — copie e guarde no seu cofre de segredos. Se perder, use Regerar secret (a integração antiga deixa de funcionar imediatamente).
4. Em Empresa → Credenciais, selecione qual webhook esta empresa específica utiliza.

Resolução por empresa

Para cada disparo, o Brasil NFe escolhe o webhook assim:

1. Se a empresa tem um webhook explicitamente vinculado (campo IdWebhook), ele é usado.
2. Senão, se existir exatamente um webhook ativo sob a mesma conta, ele é usado como fallback.
3. Se houver mais de um ativo e nenhum explicitamente vinculado, nenhum disparo acontece — a configuração é ambígua.

O envelope do payload

Cada disparo é um POST com Content-Type: application/json e o seguinte envelope:

Code
 
{
  "event": "nfe.lote.finalizado",
  "deliveryId": "9f86d081884c7d659a2feaa0c55ad015",
  "timestamp": "2026-04-28T17:32:11.0123456Z",
  "data": { /* específico do evento — ver Eventos suportados abaixo */ }
}

O envelope (event, deliveryId, timestamp, data) é sempre camelCase. O conteúdo de data segue o casing da entidade no domínio: eventos de lote (nfe.lote.*) usam camelCase; eventos de documento de entrada (documento.entrada.*) usam PascalCase (ver schema de cada evento na seção Eventos suportados).

Headers enviados

Headers extras por evento

Eventos de documento de entrada (documento.entrada.recebida, documento.entrada.cancelada) carregam dois headers adicionais para facilitar roteamento sem precisar parsear o body:

Verificação da assinatura

A assinatura é o HMAC-SHA256 do corpo bruto da requisição, codificada em hexadecimal e prefixada por sha256=. Sempre compare em tempo constante para evitar timing attacks.

Code
 
import crypto from "crypto";

function verificarAssinatura(req, secret) {
  const body = req.rawBody;
  const recebida = req.headers["x-webhook-signature"] || "";
  const esperada = "sha256=" + crypto.createHmac("sha256", secret).update(body).digest("hex");

  const a = Buffer.from(recebida);
  const b = Buffer.from(esperada);

  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Importante. Calcule o HMAC sobre o body exatamente como recebido — sem reserializar o JSON. Frameworks que parseiam o body antes de você ler costumam reordenar chaves e quebram a assinatura. No Express, use express.raw(); no ASP.NET, leia o stream antes do model binding.

Idempotência

Use o X-Webhook-Delivery (= deliveryId no body) como chave de idempotência com TTL de pelo menos 24h. Em caso de retentativas (veja abaixo) ou raros timeouts dos dois lados, o mesmo deliveryId pode chegar mais de uma vez — armazene-o e processe apenas a primeira ocorrência.

A idempotência via deliveryId é a defesa primária. O Brasil NFe garante que o mesmo evento sempre carrega o mesmo deliveryId, em todas as tentativas.

Janela anti-replay (defesa secundária)

Como o X-Webhook-Timestamp reflete o momento do disparo original, e retentativas podem chegar até ~1h12min depois, use uma janela de ±2 horas se quiser validar timestamp como camada adicional. A proteção primária contra replay deve ser a idempotência por deliveryId.

Resposta esperada

Seu endpoint deve responder 2xx em até 15 segundos. Qualquer outra coisa — erro HTTP (4xx/5xx), timeout, exceção de rede — marca a tentativa como falha. A entrega é então re-tentada automaticamente seguindo a tabela de backoff abaixo.

Se você precisa de garantia de entrega no seu lado, devolva 2xx imediatamente ao receber e processe de forma assíncrona do seu lado (fila interna). É o padrão recomendado.

Retentativas e backoff

O Brasil NFe faz até 5 tentativas de entrega para cada evento, com backoff exponencial:

Tempo total máximo: ~1h12min entre o evento e a quinta (e última) tentativa. Após a quinta tentativa falhar, o evento é considerado perdido — mas todas as tentativas ficam registradas em Painel → Webhooks → Logs para auditoria.

O que se mantém entre tentativas

• deliveryId — idêntico em todas as tentativas. Use para idempotência.
• event — idêntico.
• Body completo — byte-a-byte idêntico (logo, a X-Webhook-Signature também é idêntica).
• X-Webhook-Timestamp — reflete o disparo original, não muda.

O que muda entre tentativas

• X-Webhook-Attempt — incrementa de 1 a 5.
• URL e secret — usam a configuração atual no momento da tentativa. Se você atualizou o webhook entre o disparo original e a retentativa, a próxima tentativa vai para a nova URL com o novo secret. Webhook desativado entre tentativas → não há mais retentativas.

Eventos de teste não são re-tentados

O evento test.ping (botão "Testar" no painel) nunca é re-tentado — é uma checagem manual e o resultado é mostrado no painel imediatamente.

Eventos suportados

Mais eventos serão adicionados gradualmente. O nome do evento é estável — quando um evento entra na lista, o nome não muda.

test.ping

Disparado pelo botão Testar no painel. Nunca é re-tentado (resultado mostrado imediatamente no painel).

Headers extras: nenhum. Casing: camelCase.

nfe.lote.finalizado

Disparado quando todas as notas de um envio em lote via /EnviarNotaFiscalLote receberam resposta da SEFAZ (sucesso ou erro). É o evento de fechamento do lote — uma única notificação por lote, independente de quantas notas ele tem.

Headers extras: nenhum. Casing: camelCase.

documento.entrada.recebida

Disparado quando uma nova nota de entrada é detectada para o CNPJ da empresa: NF-e/CT-e via manifestação automática na SEFAZ, ou NFS-e capturada pelo scraping do portal nacional/da prefeitura. Mesmo que a nota já chegue cancelada, o evento de criação é sempre recebida — o consumidor identifica pelo campo Status do payload.

Headers extras: X-Document-Model, X-Document-Chave (ver acima). Casing: PascalCase.

documento.entrada.cancelada

Disparado quando uma nota de entrada previamente recebida (NF-e modelo 55 ou CT-e modelo 57) é marcada como cancelada — gatilho é o registro do evento SEFAZ 110111 (Cancelamento) associado à chave da nota.

Cancelamentos de NFS-e não passam por aqui: o cancelamento de NFS-e do portal nacional vem como nova varredura e dispara documento.entrada.recebida com Status: 2 (se a nota ainda não estava cadastrada). Notas NFS-e que já existiam no Brasil NFe não recebem evento adicional.

Headers extras: X-Document-Model, X-Document-Chave (ver acima). Casing: PascalCase.

O schema dos campos é idêntico ao de documento.entrada.recebida. A única diferença prática é o campo Status, que neste evento sempre vem como 2 (cancelado).

Code
 
{
  "event": "documento.entrada.cancelada",
  "deliveryId": "098f6bcd4621d373cade4e832627b4f6",
  "timestamp": "2026-04-29T10:15:42.0123456Z",
  "data": {
    "Chave": "35260400000000000000550010000001001000000017",
    "IdentificadorInterno": null,
    "CodLote": null,
    "Numero": 100,
    "ModeloDocumento": 55,
    "Valor": 1250.00,
    "ValorIcms": 225.00,
    "CnpjEmissor": "00000000000000",
    "NomeEmissor": "Fornecedor Exemplo LTDA",
    "IeEmissor": "1234567890123",
    "CnpjDestinatario": "11111111111111",
    "NomeDestinatario": "Sua Empresa LTDA",
    "NumeroProtocolo": "135260000000001",
    "Cfops": "5102,5405",
    "DigestValue": "xYz123abc456def789ghi012jkl345mn",
    "Status": 2,
    "DtEmissao": "2026-04-28T14:00:00",
    "DtRecebimento": "2026-04-28T17:30:00"
  }
}

Boas práticas de segurança

• Use uma URL dedicada ao webhook (ex.: /webhooks/brasilnfe) — não compartilhe com outros endpoints públicos.
• Sempre HTTPS em produção. Endereços HTTP planos serão chamados, mas o secret e o payload trafegam em claro.
• Valide a assinatura antes de qualquer parsing custoso ou consulta a banco.
• Guarde o secret em variável de ambiente ou cofre (Vault, AWS Secrets Manager, etc.), nunca no código.
• Se o secret vazou, regere imediatamente pelo painel — o secret antigo é invalidado na hora.

Teste local

Para testar sem precisar gerar uma nota real:

1. No painel, abra Webhooks e clique no ícone de avião (Testar) ao lado do webhook.
2. O Brasil NFe envia um POST com event: "test.ping" e payload mínimo.
3. Veja o resultado imediatamente (HTTP status, duração) e o request/response completo em Logs.

Para desenvolvimento local atrás de NAT, use um túnel como ngrok ou localtunnel e cadastre a URL pública gerada.