Pular para o conteúdo principal
Ver como MarkdownDocs para agentes

Catálogo de eventos de webhook — NF-e

Esta página documenta os 11 eventos de webhook do eventType product_invoice. O corpo é achatado na raiz — sem envelope payload. Veja Payloads de emissão para a regra geral dos dois envelopes.

O mesmo objeto raiz é serializado em toda ação — issued, cancelled, disabled, cce. O que muda é status e o conteúdo de lastEvents.events[], que traz o histórico de tentativas com o evento mais recente por último.

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.

Como _error e _failed se distinguem​

Em emissão, cancelamento, inutilização e CC-e, a NFE.io segue o mesmo padrão: o sufixo _failed significa que o número de tentativas se esgotou — o último evento em lastEvents tem prefixo Max* (MaxAuthorizationFailed, MaxSendToDisable, MaxSendCorrectionLetter). O sufixo _error significa uma falha pontual de tentativa — rejeição da SEFAZ ou erro técnico isolado.

Leia o type do último evento em lastEvents, não só o status raiz

status sozinho não distingue "esgotou retry" de "rejeição pontual". O campo lastEvents.events[].type sim.

Eventos de emissão​

product_invoice.issued_successfully​

Quando dispara: a NF-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
}

Note o bloco ibsCbs — aparece quando o regime tributário do emitente já está sob a reforma tributária (IBS/CBS). Se não aplicável, o campo simplesmente não vem.

Idempotency key: id ou X-Hook-Id.

product_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",
          "statusCode": 539,
          "message": "Rejeicao: Duplicidade de NF-e",
          "createdOn": "2026-08-18T00:47:30.79+00:00"
        },
        "type": "AuthorizationWithFailed",
        "sequence": 4
      }
    ],
    "hasMore": false
  }
}

Idempotency key: id.

Eventos de cancelamento​

product_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.

product_invoice.cancelled_error​

Quando dispara: a SEFAZ rejeitou o cancelamento — por exemplo, prazo legal expirado.

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

status continua Issued — o cancelamento falhou, a nota permanece válida.

Idempotency key: id.

Eventos de inutilização​

product_invoice.disabled_successfully​

Quando dispara: a faixa de numeração foi inutilizada com sucesso junto à SEFAZ.

Payload: mesmo shape base, com:

{
  "status": "Disabled",
  "lastEvents": {
    "events": [
      { "data": {}, "type": "Disabled", "sequence": 62 }
    ],
    "hasMore": true
  }
}

Idempotency key: id.

product_invoice.disabled_error​

Quando dispara: a SEFAZ rejeitou a inutilização — por exemplo, número já utilizado.

Payload: mesmo shape base, com:

{
  "status": "Error",
  "lastEvents": {
    "events": [
      {
        "data": {
          "status": "UnprocessableEntity",
          "message": "Um numero da faixa ja foi utilizado",
          "createdOn": "2026-08-18T14:18:26.10+00:00"
        },
        "type": "SentToDisableWithFailed",
        "sequence": 7
      },
      {
        "data": {
          "status": "UnprocessableEntity",
          "message": "Duplicidade de NF-e, com diferenca na Chave de Acesso.",
          "createdOn": "2026-08-18T14:16:58.75+00:00"
        },
        "type": "AuthorizationWithFailed",
        "sequence": 4
      }
    ],
    "hasMore": false
  }
}

Idempotency key: id.

product_invoice.disabled_failed​

Quando dispara: esgotou as tentativas de inutilização. Evento raro — poucas ocorrências observadas em 30 dias de produção.

Payload: mesmo shape base, com:

{
  "status": "Error",
  "lastEvents": {
    "events": [
      { "data": { "status": "MaxRetry", "createdOn": "2026-08-20T01:31:25.50+00:00" }, "type": "MaxSendToDisable", "sequence": 209 },
      { "data": { "status": "Unavailable", "createdOn": "2026-07-03T06:34:23.62+00:00" }, "type": "SendToDisableFailed", "sequence": 204 }
    ],
    "hasMore": true
  }
}

Idempotency key: id.

Eventos de Carta de Correção (CC-e)​

product_invoice.cce_successfully​

Quando dispara: a Carta de Correção foi registrada e vinculada à NF-e.

Payload: mesmo shape base, com:

{
  "status": "Issued",
  "lastEvents": {
    "events": [
      {
        "data": {
          "environmentType": "Production",
          "message": "Evento registrado e vinculado a NF-e",
          "eventDescription": "Carta de Correcao",
          "createdOn": "2026-08-18T15:25:50.83+00:00"
        },
        "type": "SentCorrectionLetterSuccessfully",
        "sequence": 8
      }
    ],
    "hasMore": false
  }
}

Idempotency key: id.

product_invoice.cce_error​

Quando dispara: a SEFAZ rejeitou a Carta de Correção — por exemplo, evento fora do schema XML esperado.

Payload: mesmo shape base, com:

{
  "status": "Issued",
  "lastEvents": {
    "events": [
      {
        "data": {
          "status": "BadRequest",
          "message": "Rejeicao: Evento nao atende o Schema XML especifico",
          "createdOn": "2026-08-11T16:52:33.68+00:00"
        },
        "type": "SentCorrectionLetterWithFailed",
        "sequence": 23
      }
    ],
    "hasMore": true
  }
}

Idempotency key: id.

product_invoice.cce_failed​

Quando dispara: esgotou as tentativas de envio da Carta de Correção. Evento extremamente raro.

Payload: mesmo shape base, com:

{
  "status": "Issued",
  "lastEvents": {
    "events": [
      { "data": { "status": "MaxRetry", "createdOn": "2026-08-17T23:45:00.06+00:00" }, "type": "MaxSendCorrectionLetter", "sequence": 208 },
      { "data": { "status": "Unavailable", "message": "Object reference not set to an instance of an object.", "createdOn": "2026-08-17T23:34:58.30+00:00" }, "type": "SendCorrectionLetterFailed", "sequence": 206 }
    ],
    "hasMore": true
  }
}

Idempotency key: id.

Como validar a assinatura​

Veja o exemplo de validação de HMAC em Dúvidas frequentes.

Veja também​

NFE.io

A NFE.io é uma empresa de tecnologia que fornece soluções para automatizar e simplificar a emissão e gestão de notas fiscais eletrônicas. Com suas ferramentas, as empresas podem economizar tempo e reduzir erros, aumentando a eficiência e precisão do processo de emissão de notas fiscais.

Um dos principais cases de sucesso da NFE.io é a implementação da solução na empresa de transporte Rodonaves. Com a automatização da emissão e gestão de notas fiscais eletrônicas, a Rodonaves conseguiu reduzir em até 80% o tempo gasto nesse processo, o que se traduziu em uma significativa melhoria na eficiência operacional. Além disso, a empresa também conseguiu eliminar erros e atrasos na emissão de notas fiscais, o que melhorou a relação com seus clientes e aumentou a confiança dos órgãos fiscais.

Outro exemplo é a implementação da NFE.io na empresa de comércio eletrônico, a Loja Integrada. Com a automatização da emissão de notas fiscais, a Loja Integrada conseguiu aumentar a velocidade de emissão de notas em até 10 vezes, o que permitiu que a empresa atendesse a uma maior quantidade de clientes e, consequentemente, aumentar as suas vendas.

Além desses exemplos, a NFE.io também tem outros cases de sucesso com empresas de setores como indústria, construção, varejo e serviços, mostrando a versatilidade e eficácia da sua solução.

Em resumo, a NFE.io é uma empresa de tecnologia que oferece soluções para automatizar e simplificar a emissão e gestão de notas fiscais eletrônicas, ajudando as empresas a economizar tempo e reduzir erros, melhorando a eficiência e precisão do processo. Com cases de sucesso em diferentes setores, a NFE.io tem se destacado como uma empresa líder em automação fiscal.