> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spedy.com.br/llms.txt
> Use this file to discover all available pages before exploring further.
# Eventos e payload
> Tipos de eventos e formato do payload dos webhooks.
## 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](/guides/notas-recebidas/nfe/visao-geral) e
[NFS-e tomadas](/guides/notas-recebidas/nfse/visao-geral).
| 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](/webhooks/gerenciamento)). 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](/guides/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:
```json theme={null}
{
"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](/webhooks/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](#exemplo-de-payload-notas-recebidas) mais abaixo, e o conceito em
[NF-e recebidas](/guides/notas-recebidas/nfe/visao-geral) e
[NFS-e tomadas](/guides/notas-recebidas/nfse/visao-geral).
## 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.
```json theme={null}
{
"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](/webhooks/visao-geral)) e `data.status` para
saber o estado atual da nota (veja [Ciclo de vida da
nota](/guides/ciclo-de-vida-da-nota) para o significado de cada
valor).
## Exemplo de payload — notas recebidas
Os eventos de notas recebidas ([NF-e](/guides/notas-recebidas/nfe/visao-geral)
e [NFS-e](/guides/notas-recebidas/nfse/visao-geral)) 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`
```json theme={null}
{
"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.
```json theme={null}
{
"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.
```json theme={null}
{
"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.