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

Catálogo de eventos de webhook — Documentos recebidos

Esta página é a referência completa dos 4 eventTypes de entrada — documentos que terceiros emitem contra o seu CNPJ e que a NFE.io captura para você. Para o guia didático desses eventos, veja Payloads de webhooks de documentos recebidos.

Todos os eventos de entrada entregam os campos achatados na raiz, sem envelope.

Política de entrega​

  • Entrega: at-least-once. Garanta idempotência por X-Hook-Id e, quando disponível, nsu.
  • 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.

Os 4 tipos​

eventTypeDocumentoQuando dispara
product_invoice_inboundNF-e completaNF-e autorizada contra seu CNPJ, com XML disponível
product_invoice_inbound_summaryResumo de NF-eSó metadados — XML completo ainda não liberado pela SEFAZ
transportation_invoice_inboundCT-eCT-e em que sua empresa é destinatária, tomadora, remetente ou emitente
service_invoice_inboundNFS-e recebidaNFS-e capturada contra seu CNPJ

Como event_raised_successfully e input_event_raised_successfully se distinguem​

Ambas as ações representam um evento vinculado a uma NF-e já recebida — não a nota em si. A diferença está no código do evento da SEFAZ:

  • input_event_raised_successfully dispara para os 4 eventos de Manifestação do Destinatário: código 210200 (Confirmação da Operação), 210210 (Ciência da Operação), 210220 (Desconhecimento da Operação) e 210240 (Operação não Realizada).
  • event_raised_successfully dispara para qualquer outro evento — Carta de Correção, Cancelamento, EPEC, e os demais eventos do layout da NF-e.

Para o tipo resumo (product_invoice_inbound_summary), a ação de evento é sempre event_raised_successfully — não existe input_event_raised_successfully no shape de resumo.

Eventos de NF-e (product_invoice_inbound)​

product_invoice_inbound.issued_successfully​

Quando dispara: uma NF-e completa foi recebida contra o seu CNPJ, com XML disponível.

Payload:

{
  "accessKey": "20067692631216642359468835243948726939910022",
  "createdOn": "2026-08-18T00:48:02.58Z",
  "parentAccessKey": "",
  "company": {
    "id": "fb487ff47f108587",
    "federalTaxNumber": "44338200330345"
  },
  "issuer": {
    "federalTaxNumber": "44338200330345",
    "name": "Papelaria Horizonte LTDA"
  },
  "buyer": {
    "federalTaxNumber": "44338200330345",
    "name": "Tecnologia Meridiano LTDA"
  },
  "transportation": {
    "federalTaxNumber": "44338200330345",
    "name": "Grafica Estrela do Sul LTDA"
  },
  "links": {
    "xml": "https://exemplo.nfe.io/xml/nota.xml",
    "pdf": "https://exemplo.nfe.io/pdf/nota.pdf"
  },
  "blobUrl": "b2://dfenfe/exemplo/documento.xml",
  "type": "productInvoice",
  "nsu": "000000012345678",
  "nsuParent": "",
  "nfeNumber": "53145",
  "nfeSerialNumber": "0",
  "issuedOn": "2026-08-17T15:56:40+00:00",
  "totalInvoiceAmount": "1258.60",
  "operationType": "Incoming",
  "environmentType": 0,
  "direction": "Received"
}

Idempotency key: accessKey + nsu.

product_invoice_inbound.event_raised_successfully​

Quando dispara: um evento não-manifestação foi registrado contra uma NF-e já recebida — por exemplo, Carta de Correção (código 610130 no exemplo abaixo).

Payload: mesmo shape base, campo type vira productInvoiceEvent, e ganha o bloco event:

{
  "accessKey": "20067692631216642359468835243948726939910022",
  "createdOn": "2026-08-18T00:56:44.68Z",
  "parentAccessKey": "20067692631216642359468835243948726939910099",
  "company": { "id": "fb487ff47f108587", "federalTaxNumber": "44338200330345" },
  "issuer": { "federalTaxNumber": "44338200330345", "name": "Papelaria Horizonte LTDA" },
  "buyer": { "federalTaxNumber": "44338200330345", "name": "Tecnologia Meridiano LTDA" },
  "transportation": { "federalTaxNumber": "44338200330345", "name": "Grafica Estrela do Sul LTDA" },
  "links": { "xml": "https://exemplo.nfe.io/xml/evento.xml", "pdf": "" },
  "blobUrl": "b2://dfenfe/exemplo/evento.xml",
  "type": "productInvoiceEvent",
  "nsu": "000000012345679",
  "nsuParent": "000000012345678",
  "nfeNumber": "665779",
  "nfeSerialNumber": "1",
  "issuedOn": "2026-08-13T13:29:00+00:00",
  "totalInvoiceAmount": "50713",
  "operationType": "Incoming",
  "environmentType": 0,
  "event": {
    "id": "e87a03a3152b73f1",
    "code": 610130,
    "sequence": 1,
    "receiptOn": "2026-08-17T23:49:02+00:00"
  }
}

nsuParent aponta para o nsu do documento original — use-o para relacionar o evento à NF-e que ele modifica.

Idempotency key: accessKey + nsu.

product_invoice_inbound.input_event_raised_successfully​

Quando dispara: você (ou seu sistema) registrou uma Manifestação do Destinatário — Confirmação, Ciência, Desconhecimento ou Operação Não Realizada.

Payload: mesmo shape de event_raised_successfully, com event.code sendo um dos 4 valores de manifestação:

{
  "event": {
    "id": "e87a03a3152b73f1",
    "code": 210200,
    "sequence": 1,
    "receiptOn": "2026-08-17T23:49:02+00:00"
  }
}
event.codeManifestação
210200Confirmação da Operação
210210Ciência da Operação
210220Desconhecimento da Operação
210240Operação não Realizada

Idempotency key: accessKey + nsu.

Eventos de resumo de NF-e (product_invoice_inbound_summary)​

O resumo chega quando a SEFAZ ainda não liberou o XML completo. Comparado ao tipo completo, faltam buyer, transportation, nfeSerialNumber e links.pdf; e issuedOn aqui reflete a data de recebimento na distribuição (não a data de emissão do XML original).

issuedOn no resumo não é a data de emissão

No tipo completo, issuedOn vem do XML da nota. No resumo, issuedOn vem do recebimento na distribuição SEFAZ — pode ser dias depois da emissão real. Não trate como data de emissão sem conferir.

product_invoice_inbound_summary.issued_successfully​

Payload:

{
  "accessKey": "20067692631216642359468835243948726939910022",
  "createdOn": "2026-08-18T00:48:02.52Z",
  "company": {
    "id": "fb487ff47f108587",
    "federalTaxNumber": "44338200330345"
  },
  "issuer": {
    "federalTaxNumber": "44338200330345",
    "name": "Papelaria Horizonte LTDA"
  },
  "links": {
    "xml": "https://exemplo.nfe.io/xml/resumo.xml"
  },
  "blobUrl": "b2://dfenfe/exemplo/resumo.xml",
  "type": "productInvoiceSummary",
  "nsu": "000000012345680",
  "nfeNumber": "000207820",
  "issuedOn": "2026-08-17T20:35:37+00:00",
  "totalInvoiceAmount": "2786.00",
  "operationType": "Outgoing",
  "environmentType": 0,
  "direction": "Received"
}

Idempotency key: accessKey + nsu.

product_invoice_inbound_summary.event_raised_successfully​

Payload: mesmo shape do resumo, com type: "productInvoiceSummaryEvent" e bloco event — sempre event_raised_successfully, nunca input_event_raised_successfully, mesmo para manifestação:

{
  "accessKey": "20067692631216642359468835243948726939910022",
  "createdOn": "2026-08-18T00:56:44.68Z",
  "parentAccessKey": "20067692631216642359468835243948726939910099",
  "company": { "id": "fb487ff47f108587", "federalTaxNumber": "44338200330345" },
  "issuer": { "federalTaxNumber": "44338200330345", "name": "Papelaria Horizonte LTDA" },
  "links": { "xml": "https://exemplo.nfe.io/xml/evento-resumo.xml", "pdf": "" },
  "blobUrl": "b2://dfenfe/exemplo/evento-resumo.xml",
  "type": "productInvoiceSummaryEvent",
  "nsu": "000000012345679",
  "nfeNumber": "665779",
  "issuedOn": "2026-08-13T13:29:00+00:00",
  "totalInvoiceAmount": "50713",
  "operationType": "Incoming",
  "environmentType": 0,
  "event": {
    "id": "e87a03a3152b73f1",
    "code": 610130,
    "sequence": 1,
    "receiptOn": "2026-08-17T23:49:02+00:00"
  }
}

Idempotency key: accessKey + nsu.

Eventos de CT-e (transportation_invoice_inbound)​

transportation_invoice_inbound.issued_successfully​

Quando dispara: um CT-e foi recebido em que sua empresa é destinatária, tomadora ou remetente (direction: "Received").

Payload:

{
  "recipient": { "federalTaxNumber": "44338200330345", "name": "Industria Ponta Norte S.A." },
  "sender": { "federalTaxNumber": "44338200330345", "name": "Grafica Estrela do Sul LTDA" },
  "taker": { "federalTaxNumber": "44338200330345", "name": "Metalurgica Boa Vista LTDA" },
  "dispatcher": { "federalTaxNumber": "44338200330345", "name": "Atacado Ferreira & Filhos LTDA" },
  "issuedOn": "2026-08-17T20:00:31+00:00",
  "productInvoices": [{ "accessKey": "77838944273181403097002144935518350097110030" }],
  "totalAmount": "6.71",
  "direction": "Received",
  "id": "9945c26da840f80a",
  "createdOn": "2026-08-18T00:49:20.01Z",
  "accessKey": "20067692631216642359468835243948726939910022",
  "parentAccessKey": "",
  "nsu": "000000012345678",
  "company": { "id": "fb487ff47f108587" },
  "type": "transportationInvoice",
  "xmlUrl": "https://exemplo.nfe.io/xml/cte.xml"
}

productInvoices[] lista as NF-e vinculadas ao CT-e, quando houver.

Idempotency key: accessKey + nsu.

transportation_invoice_inbound.outbound_successfully​

Quando dispara: um CT-e retornado pela distribuição SEFAZ tem sua própria conta como emitente (direction: "Issued") — não é um documento de terceiro chegando, é seu próprio CT-e aparecendo no canal de distribuição.

Payload: mesmo shape base, com direction: "Issued":

{
  "recipient": { "federalTaxNumber": "44338200330345", "name": "Industria Ponta Norte S.A." },
  "sender": { "federalTaxNumber": "44338200330345", "name": "Grafica Estrela do Sul LTDA" },
  "taker": { "federalTaxNumber": "44338200330345", "name": "Metalurgica Boa Vista LTDA" },
  "dispatcher": { "federalTaxNumber": "44338200330345", "name": "Atacado Ferreira & Filhos LTDA" },
  "issuedOn": "2026-08-17T18:35:17+00:00",
  "productInvoices": [{ "accessKey": "77838944273181403097002144935518350097110030" }],
  "totalAmount": "15.60",
  "direction": "Issued",
  "id": "9945c26da840f80a",
  "createdOn": "2026-08-18T01:32:28.00Z",
  "accessKey": "20067692631216642359468835243948726939910022",
  "parentAccessKey": "",
  "nsu": "000000012345678",
  "company": { "id": "fb487ff47f108587", "federalTaxNumber": "44338200330345" },
  "type": "transportationInvoice",
  "xmlUrl": "https://exemplo.nfe.io/xml/cte.xml"
}

Esta ação foi observada até hoje apenas em CT-e. O mecanismo interno é genérico por direção do documento — se você emitir NF-e e ela retornar pela distribuição, o mesmo padrão pode se aplicar.

Idempotency key: accessKey + nsu.

transportation_invoice_inbound.event_raised_successfully​

Quando dispara: um evento foi registrado contra um CT-e já recebido.

Payload:

{
  "receiptOn": "2026-08-18T05:46:39+00:00",
  "id": "9945c26da840f80a",
  "createdOn": "2026-08-18T09:02:15.12Z",
  "accessKey": "20067692631216642359468835243948726939910022",
  "parentAccessKey": "20067692631216642359468835243948726939910099",
  "nsu": "000000012345679",
  "company": { "id": "fb487ff47f108587" },
  "type": "transportationInvoiceEvent",
  "xmlUrl": "https://exemplo.nfe.io/xml/evento-cte.xml"
}

Idempotency key: accessKey + nsu.

Eventos de NFS-e recebida (service_invoice_inbound)​

Este eventType usa um shape diferente dos demais — envelope próprio com eventName, document aninhado e campos fiscais completos (taxes, amounts).

service_invoice_inbound.issued_successfully​

Payload:

{
  "eventName": "inbound.serviceInvoice.received",
  "type": "serviceInvoice",
  "accountId": "77b8ce7fc7e8f57e",
  "document": {
    "id": "32698345792ade4c",
    "direction": "Received",
    "accessKey": "07027571856179777714472370526884045867942652",
    "generatedOn": "2026-08-17T20:18:07Z",
    "issuedOn": "2026-08-17T17:18:07-03:00",
    "provider": {
      "federalTaxNumber": "44338200330345",
      "name": "Transportes Rio Claro LTDA",
      "state": "RJ"
    },
    "borrower": {
      "federalTaxNumber": "44338200330345",
      "name": "Grafica Estrela do Sul LTDA",
      "state": null
    },
    "servicesAmount": 1799.20,
    "federalServiceCode": "010501",
    "cityServiceCode": "001",
    "amounts": {
      "amountNet": 1799.20
    },
    "taxes": {
      "regime": { "simplesNacionalOption": "1", "specialTaxRegime": "0" },
      "issqn": { "situationCode": "1", "retentionType": "1", "base": 1799.20, "rate": 2.90, "amount": 52.17 },
      "ibsCbs": {
        "situationCode": "000",
        "classCode": "000001",
        "operationIndicator": "100501",
        "incidenceCity": { "code": "2927408", "name": "Salvador" },
        "basis": 1747.02,
        "ibs": { "state": { "rate": 0.10, "amount": 1.74 }, "municipal": { "rate": 0.00, "amount": 0.00 }, "totalAmount": 1.75 },
        "cbs": { "rate": 0.90, "amount": 15.72 }
      }
    },
    "environment": "Production",
    "xmlUrl": "https://exemplo.nfe.io/xml/nfse.xml",
    "pdfUrl": "https://exemplo.nfe.io/pdf/nfse.pdf"
  }
}

Campos nulos (como provider.state quando a prefeitura não informa) são enviados como null neste eventType — diferente do padrão de emissão, que costuma omitir o campo.

Idempotency key: document.id ou document.accessKey.

service_invoice_inbound.event_raised_successfully​

Quando dispara: um evento foi registrado contra uma NFS-e recebida — por exemplo, cancelamento pelo prestador.

Payload:

{
  "eventName": "inbound.serviceInvoice.event.received",
  "accountId": "77b8ce7fc7e8f57e",
  "document": {
    "id": "32698345792ade4c",
    "type": "serviceInvoiceEvent",
    "eventType": "Cancellation",
    "eventCode": "101101",
    "accessKey": "07027571856179777714472370526884045867942652",
    "generatedOn": "2026-08-17T03:00:00Z",
    "issuedOn": null,
    "provider": null,
    "borrower": null,
    "environment": "Production",
    "xmlUrl": "https://exemplo.nfe.io/xml/evento-nfse.xml",
    "pdfUrl": null
  }
}

Quando o evento não carrega dados fiscais completos (como um cancelamento), provider, borrower e os blocos de valores vêm null em vez de omitidos.

Idempotency key: document.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.