Catálogo de eventos de webhook — NFC-e
Esta página documenta os 5 eventos de webhook do eventType consumer_invoice. O corpo é achatado na raiz — sem envelope payload, o mesmo padrão de NF-e. Veja Payloads de emissão para a regra geral dos dois envelopes.
NFC-e compartilha o mesmo mecanismo interno de NF-e: um único objeto raiz serializado para toda ação, variando status e lastEvents.events[]. Se você já integrou com NF-e, o parser é o mesmo — só troca o eventType assinado.
O comprador de uma NFC-e é frequentemente pessoa física. Trate buyer/CPF/e-mail como dado sensível e não grave em log aberto.
Política de entrega
- Entrega: at-least-once. Garanta idempotência por
X-Hook-Id. - Retry: reentrega automática em falha de rede ou resposta não-2xx.
- Timeout: responda 2xx rápido e processe de forma assíncrona.
- Assinatura: valide o HMAC do cabeçalho antes de processar. Veja Dúvidas frequentes.
Eventos de emissão
consumer_invoice.issued_successfully
Quando dispara: a NFC-e foi autorizada pela SEFAZ.
Payload:
{
"id": "9945c26da840f80a",
"serie": 1,
"number": 3480,
"status": "Issued",
"authorization": {
"accessKey": "77861115023072680707914995505469053510672837"
},
"operationNature": "Venda de mercadorias",
"issuer": {
"tradeName": "Grafica Estrela do Sul LTDA",
"taxRegime": "SimplesNacional",
"specialTaxRegime": "Automatico",
"accountId": "ce02bb4dbb03d9bb",
"id": "6e232f2a3f1cd1bb",
"name": "Papelaria Horizonte LTDA",
"federalTaxNumber": "44338200330345",
"address": {
"street": "Alameda dos Ipes",
"number": "594",
"city": { "code": "3304557", "name": "Rio de Janeiro" },
"state": "RJ",
"postalCode": "22402-835",
"country": "BRA"
},
"type": "LegalEntity"
},
"totals": {
"icms": { "baseTax": 0, "productAmount": 45.5, "invoiceAmount": 45.5 },
"ibsCbs": { "basis": 45.5, "ibs": { "totalAmount": 0.04 }, "cbs": { "amount": 0.41 } }
},
"transport": { "freightModality": "Free" },
"payment": [
{ "paymentDetail": [{ "method": "InstantPayment", "amount": 45.5, "card": {} }], "payBack": 0 }
],
"lastEvents": {
"events": [
{
"data": {
"accessKey": "85659627122586874265656938753615893000772971",
"environmentType": "Production",
"statusCode": 100,
"createdOn": "2026-08-18T00:47:30.79+00:00"
},
"type": "Authorized",
"sequence": 4
}
],
"hasMore": false
},
"apiVersion": 2
}
Idempotency key: id ou X-Hook-Id.
consumer_invoice.issued_error
Quando dispara: a SEFAZ rejeitou a autorização — falha pontual, não esgotamento de retry.
Payload: mesmo shape base, com:
{
"status": "Error",
"lastEvents": {
"events": [
{
"data": {
"status": "BadRequest",
"message": "Rejeicao: Duplicidade de NFC-e",
"createdOn": "2026-08-18T00:47:30.79+00:00"
},
"type": "AuthorizationWithFailed",
"sequence": 4
}
],
"hasMore": false
}
}
Idempotency key: id.
consumer_invoice.issued_failed
Quando dispara: esgotou as tentativas de autorização — frequentemente por indisponibilidade da SEFAZ estadual.
Payload: mesmo shape base, com:
{
"status": "Error",
"lastEvents": {
"events": [
{ "data": { "status": "MaxRetry", "createdOn": "2026-08-16T08:39:38.82+00:00" }, "type": "MaxAuthorizationFailed", "sequence": 204 },
{ "data": { "status": -6, "message": "Connection refused (nfce.sefaz.mt.gov.br:443)", "createdOn": "2026-08-16T08:29:37.55+00:00" }, "type": "SendSignedBatchFailed", "sequence": 202 }
],
"hasMore": true
}
}
O histórico deixa explícito o motivo raiz — aqui, indisponibilidade de rede da SEFAZ do estado. Use lastEvents para diagnóstico, não apenas status.
Idempotency key: id.
Eventos de cancelamento
consumer_invoice.cancelled_successfully
Quando dispara: o cancelamento foi homologado pela SEFAZ.
Payload: mesmo shape base, com:
{
"status": "Cancelled",
"lastEvents": {
"events": [
{ "data": { "createdOn": "2026-08-18T10:12:05.30+00:00" }, "type": "MergedCancellation", "sequence": 9 }
],
"hasMore": false
}
}
Idempotency key: id.
consumer_invoice.cancelled_error
Quando dispara: a SEFAZ rejeitou o cancelamento — por exemplo, prazo legal expirado. Evento raro em NFC-e — poucas ocorrências em 30 dias de produção.
Payload: mesmo shape base, com:
{
"status": "Issued",
"lastEvents": {
"events": [
{
"data": {
"status": "BadRequest",
"message": "Prazo de cancelamento superior ao previsto na Legislacao",
"createdOn": "2026-08-18T01:02:18.46+00:00"
},
"type": "SentToCancelWithFailed",
"sequence": 8
}
],
"hasMore": false
}
}
Idempotency key: id.
Como validar a assinatura
Veja o exemplo de validação de HMAC em Dúvidas frequentes.