Catálogo de eventos de webhook
A NFE.io publica eventos de webhook em duas famílias: eventos de saída — o que a sua conta emite (NFS-e, NF-e, NFC-e, guias e regras fiscais) — e eventos de entrada — documentos de terceiros que a NFE.io captura contra o seu CNPJ (NF-e, CT-e, NFS-e recebidas). Esta página indexa as duas.
Política de entrega
- Entrega: at-least-once. Garanta idempotência — nunca assuma que um evento chega uma única vez.
- Retry: reentrega automática em falha de rede ou resposta HTTP fora da faixa 2xx.
- Timeout: responda 2xx rápido e processe de forma assíncrona. Retornar erro faz a NFE.io reenviar o mesmo evento.
- Assinatura: todo evento é assinado por HMAC no cabeçalho. Valide antes de processar — veja Dúvidas frequentes.
Como descobrir qual evento chegou
| Origem | O que traz |
|---|---|
Cabeçalho X-Hook-Event | o eventType (ex.: service_invoice) |
Cabeçalho X-Hook-Id | identificador único da entrega — use para deduplicar |
Cabeçalho X-Hook-Attempts | número da tentativa |
Corpo (flowStatus/status) | o resultado da operação |
Os dois envelopes
| eventType | Família | Envelope |
|---|---|---|
service_invoice | Saída (NFS-e) | {"payload": {...}} |
product_invoice | Saída (NF-e) | achatado na raiz |
consumer_invoice | Saída (NFC-e) | achatado na raiz |
product_tax, tax_payment_form | Saída (outros) | achatado na raiz |
product_invoice_inbound, *_summary | Entrada | achatado na raiz |
transportation_invoice_inbound | Entrada | achatado na raiz |
service_invoice_inbound | Entrada | achatado na raiz (envelope próprio com document) |
Eventos de saída
O que a sua conta emite. 24 eventos cobertos, agrupados por produto:
| Página | Produto | Eventos |
|---|---|---|
| Catálogo de saída — NFS-e | Nota Fiscal de Serviço | 7 — emissão, cancelamento (sucesso e falha) |
| Catálogo de saída — NF-e | Nota Fiscal Eletrônica | 11 — emissão, cancelamento, inutilização, Carta de Correção |
| Catálogo de saída — NFC-e | Nota Fiscal de Consumidor | 5 — emissão, cancelamento |
| Catálogo de saída — Outros eventos | Regras fiscais e guias | 4 — product_tax, tax_payment_form |
Eventos de entrada
O que a NFE.io captura contra o seu CNPJ. 10 eventos, em uma única página de referência:
| Página | Cobre |
|---|---|
| Catálogo de entrada — Documentos recebidos | NF-e, resumo de NF-e, CT-e e NFS-e recebidos, incluindo manifestação do destinatário |
Para o guia didático dos eventos de entrada — com contexto de uso e exemplos de parsing — veja Payloads de webhooks de documentos recebidos.
Como validar a assinatura
Veja o exemplo de validação de HMAC em Dúvidas frequentes.