Eventos e payload

Eventos disponíveis

Emissão

Eventos das notas que a sua empresa emite.

Evento	Descrição
`invoice.status_changed`	Qualquer alteração de status da nota (criação, autorização, rejeição, cancelamento etc.)
`invoice.authorized`	Nota fiscal autorizada
`invoice.rejected`	Nota fiscal rejeitada
`invoice.canceled`	Nota fiscal cancelada
`invoice.contingency`	Nota fiscal emitida em contingência, aguardando autorização definitiva

Notas recebidas

Eventos das notas emitidas contra o seu CNPJ por terceiros — veja NF-e recebidas e NFS-e tomadas.

Evento	Descrição	Modelos
`inbound_invoice.detected`	Nova nota recebida detectada na distribuição. Na NF-e ela chega como resumo (`isComplete: false`); na NFS-e é entregue completa	NF-e e NFS-e
`inbound_invoice.completed`	Nota recebida com o XML autorizado completo liberado, após a manifestação	Só NF-e
`inbound_invoice.event`	Novo evento vinculado a uma nota recebida (ex.: cancelamento pelo emissor, carta de correção na NF-e, manifestação registrada)	NF-e e NFS-e

inbound_invoice.completed não é disparado para NFS-e. O evento anuncia a passagem de resumo para XML completo, transição que existe apenas na NF-e — a NFS-e é entregue completa pelo ambiente nacional. Integrações que aguardam esse evento para obter o XML de uma NFS-e não serão notificadas; utilize o detected.

Os três eventos são compartilhados pelos dois modelos. O campo model do payload identifica o modelo recebido: productInvoice para NF-e, serviceInvoice para NFS-e. Cada webhook assina um único evento (campo event em WebhookEditingDto, veja Gerenciamento de webhooks). Para receber mais de um tipo, crie um webhook por evento. Na maioria dos casos, assinar apenas invoice.status_changed é suficiente — ele cobre todo o ciclo de vida da nota (veja Ciclo de vida da nota), incluindo as mesmas transições que os eventos mais específicos (invoice.authorized, invoice.rejected, invoice.canceled) também disparam. Use os eventos específicos apenas se sua integração precisa reagir de forma diferenciada a cada um sem inspecionar o data.status do payload.

Envelope do payload

Todo evento é entregue como um HTTP POST com o corpo no seguinte formato:

{
  "id": "uuid-do-evento",
  "event": "invoice.status_changed",
  "data": { ... }
}

Campo	Descrição
`id`	Identificador único do evento. Use-o para deduplicar entregas repetidas (a mesma entrega pode chegar mais de uma vez). É o mesmo valor do header `webhook-id` da assinatura.
`event`	Um dos eventos disponíveis (tabela acima).
`data`	Objeto completo da nota fiscal que gerou o evento — o mesmo formato retornado pelo endpoint `GET` correspondente (`/v1/service-invoices/{id}`, `/v1/product-invoices/{id}` ou `/v1/consumer-invoices/{id}`).

Nos eventos de notas recebidas (inbound_invoice.*), o data varia por evento: em inbound_invoice.detected e inbound_invoice.completed traz o objeto da nota recebida — no formato de GET /v1/inbound-product-invoices/{id} para NF-e ou de GET /v1/inbound-service-invoices/{id} para NFS-e; em inbound_invoice.event traz { invoice, event }. Veja os exemplos em Notas recebidas mais abaixo, e o conceito em NF-e recebidas e NFS-e tomadas.

Exemplo de payload

O exemplo abaixo é de uma autorização de NFS-e. O data contém os mesmos campos retornados por GET /v1/service-invoices/{id} — a estrutura é idêntica para NF-e e NFC-e, usando os campos dos respectivos endpoints de leitura.

{
  "id": "caaf34ab-6c65-4ca6-b6bf-b2d8f497c721",
  "event": "invoice.status_changed",
  "data": {
    "id": "833e8e0e-3bda-4394-ab70-5edf4ee70988",
    "status": "authorized",
    "rps": {
      "number": 1,
      "series": "1"
    },
    "batchNumber": 1,
    "model": "serviceInvoice",
    "environmentType": "production",
    "issuedOn": "2021-11-08T18:35:37.823708",
    "receiver": {
      "name": "EMPRESA LTDA",
      "federalTaxNumber": "00000571000189",
      "municipalTaxNumber": null,
      "email": null,
      "phoneNumber": null,
      "address": {
        "street": "Estrada da Água Branca",
        "district": "Padre Miguel",
        "postalCode": "21720162",
        "number": "3795",
        "additionalInformation": null,
        "city": {
          "name": "Rio de Janeiro",
          "state": "RJ"
        }
      }
    },
    "company": {
      "name": "EMPRESA LTDA",
      "legalName": "EMPRESA LTDA",
      "federalTaxNumber": "00000571000189",
      "stateTaxNumber": "634992136797",
      "cityTaxNumber": "123456"
    },
    "order": {
      "id": "fa15d7af-991d-467d-961a-f564b76d771c",
      "date": "2021-10-14T09:00:00",
      "transactionId": "AACcacAD1DB"
    },
    "authorization": {
      "date": "2021-11-08T18:35:38.443559",
      "protocol": "AAAB1245",
      "digestValue": null
    },
    "amount": 100,
    "number": 0,
    "processingDetail": {
      "status": "success",
      "message": "NFS-e autorizada pelo município.",
      "code": null,
      "on": "2021-11-08T18:35:38.443559"
    }
  }
}

Use data.company para identificar a empresa que gerou o evento (lembre-se: o webhook é por conta e recebe eventos de todas as empresas — veja Webhooks: visão geral) e data.status para saber o estado atual da nota (veja Ciclo de vida da nota para o significado de cada valor).

Exemplo de payload — notas recebidas

Os eventos de notas recebidas (NF-e e NFS-e) têm um data diferente dos eventos de emissão — e que varia conforme o evento.

`inbound_invoice.detected` e `inbound_invoice.completed`

Nos dois eventos, o data é o objeto da nota recebida — o mesmo formato do GET correspondente ao modelo: /v1/inbound-product-invoices/{id} para NF-e, /v1/inbound-service-invoices/{id} para NFS-e. O campo model diz qual dos dois você recebeu. Na NF-e, o que muda entre os dois eventos é o estágio da nota:

inbound_invoice.detected: a nota acabou de ser detectada, ainda como resumo — isComplete: false e sem manifestação.
inbound_invoice.completed: o mesmo objeto depois de manifestado — isComplete: true e manifestation preenchida.

Na NFS-e ocorre apenas o detected, e a nota já é entregue com isComplete: true.

NF-e — `inbound_invoice.detected`

{
  "id": "b1e5c0a2-9d47-4f6e-9c8a-3e2f1d0a7b64",
  "event": "inbound_invoice.detected",
  "data": {
    "id": "9f3c8d21-4a5b-4c6d-8e7f-0a1b2c3d4e5f",
    "model": "productInvoice",
    "company": {
      "name": "MINHA EMPRESA LTDA",
      "legalName": "MINHA EMPRESA LTDA",
      "federalTaxNumber": "00000571000189",
      "stateTaxNumber": "634992136797",
      "cityTaxNumber": null
    },
    "environmentType": "production",
    "accessKey": "52260778876950012340551780047261641231129462",
    "nsu": 10432,
    "isComplete": false,
    "status": "authorized",
    "issuer": {
      "name": "FORNECEDOR ABC INDUSTRIA LTDA",
      "legalName": "FORNECEDOR ABC INDUSTRIA LTDA",
      "federalTaxNumber": "12345678000199",
      "stateTaxNumber": "110042490114",
      "cityTaxNumber": null,
      "address": {
        "street": "Av. das Indústrias",
        "district": "Distrito Industrial",
        "postalCode": "13480000",
        "number": "1000",
        "additionalInformation": null,
        "city": { "name": "Limeira", "state": "SP" }
      }
    },
    "issuedOn": "2026-07-20T14:35:10",
    "amount": 1540.90,
    "operationType": "outgoing",
    "manifestation": {
      "status": "none",
      "date": null,
      "protocol": null,
      "justification": null
    },
    "events": [],
    "creationTime": "2026-07-21T03:12:44",
    "lastModificationTime": null
  }
}

NFS-e — `inbound_invoice.detected`

Mesmo envelope, com o corpo do modelo de serviço. As diferenças em relação ao exemplo anterior: isComplete já é verdadeiro na detecção, a chave de acesso tem 50 dígitos, role indica o papel da empresa na nota e manifestation não traz protocol — o ambiente nacional não emite protocolo para evento de NFS-e.

{
  "id": "d4a7f2b8-1c39-4e5a-8b60-7d9e0f1a2c35",
  "event": "inbound_invoice.detected",
  "data": {
    "id": "3b8e6d04-7f21-4a9c-b5e3-1d0c9a8f7e62",
    "model": "serviceInvoice",
    "company": {
      "name": "MINHA EMPRESA LTDA",
      "legalName": "MINHA EMPRESA LTDA",
      "federalTaxNumber": "00000571000189",
      "stateTaxNumber": "634992136797",
      "cityTaxNumber": "1234567"
    },
    "environmentType": "production",
    "accessKey": "35503082298765432000188260800000000012740000012743",
    "nsu": 2087,
    "isComplete": true,
    "status": "authorized",
    "issuer": {
      "name": "CONSULTORIA XYZ SERVICOS LTDA",
      "legalName": "CONSULTORIA XYZ SERVICOS LTDA",
      "federalTaxNumber": "98765432000188",
      "stateTaxNumber": null,
      "cityTaxNumber": "7654321",
      "address": {
        "street": "Rua das Palmeiras",
        "district": "Centro",
        "postalCode": "01310000",
        "number": "250",
        "additionalInformation": "Conjunto 82",
        "city": { "name": "São Paulo", "state": "SP" }
      }
    },
    "issuedOn": "2026-08-14T10:02:00",
    "amount": 4800.00,
    "number": 1274,
    "serviceDescription": "Consultoria em arquitetura de software — agosto/2026",
    "serviceLocation": "São Paulo",
    "role": "recipient",
    "manifestation": {
      "status": "none",
      "date": null,
      "justification": null,
      "reasonCode": null
    },
    "events": [],
    "creationTime": "2026-08-14T11:40:12",
    "lastModificationTime": null
  }
}

`inbound_invoice.event`

Disparado quando um evento fiscal é vinculado à nota (cancelamento ou carta de correção feitos pelo emitente, por exemplo). Aqui o data é um envelope { invoice, event }: a nota e o evento específico que disparou — porque a nota sozinha não diz qual evento ocorreu.

{
  "id": "c2d6e1b3-0e58-4a7f-bd9b-4f3a2e1c5d70",
  "event": "inbound_invoice.event",
  "data": {
    "invoice": {
      "id": "9f3c8d21-4a5b-4c6d-8e7f-0a1b2c3d4e5f",
      "accessKey": "52260778876950012340551780047261641231129462",
      "status": "canceled",
      "isComplete": true
      // ...demais campos da nota, iguais ao exemplo acima...
    },
    "event": {
      "id": "7a1f9c34-2b6d-4e8a-9f10-5c4b3a2d1e0f",
      "type": "cancellation",
      "eventCode": "110111",
      "sequenceNumber": 1,
      "date": "2026-07-22T09:05:00",
      "protocol": "135260000112233",
      "description": "Cancelamento registrado pelo emitente."
    }
  }
}

O campo event.type indica o tipo do evento, e os valores possíveis dependem do modelo:

`model`	Valores de `event.type`
`productInvoice` (NF-e)	`cancellation`, `correctionLetter`, `delivery`, `manifestation`, `other`
`serviceInvoice` (NFS-e)	`cancellation`, `manifestation`, `other`

O exemplo acima é de NF-e. Na NFS-e o envelope é o mesmo, com duas diferenças no objeto event: não há protocol (o ambiente nacional não emite protocolo para evento de NFS-e) e o eventCode segue a numeração do padrão nacional — por exemplo 101101 para o cancelamento e 203202 para a confirmação do tomador.

​Eventos disponíveis

​Emissão

​Notas recebidas

​Envelope do payload

​Exemplo de payload

​Exemplo de payload — notas recebidas

​inbound_invoice.detected e inbound_invoice.completed

​NF-e — inbound_invoice.detected

​NFS-e — inbound_invoice.detected

​inbound_invoice.event

Eventos disponíveis

Emissão

Notas recebidas

Envelope do payload

Exemplo de payload

Exemplo de payload — notas recebidas

`inbound_invoice.detected` e `inbound_invoice.completed`

NF-e — `inbound_invoice.detected`

NFS-e — `inbound_invoice.detected`

`inbound_invoice.event`