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

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

<Note>
  `invoice.contingency` está documentado na descrição do endpoint `POST
      /v1/webhooks` e na seção de [Contingência](/pages/guides/contingencia) da
  referência da API, mas não aparece na lista de valores aceitos do campo
  `event` de `WebhookEditingDto` no schema OpenAPI (que lista apenas
  `invoice.status_changed`, `invoice.authorized`, `invoice.rejected` e
  `invoice.canceled`). Há uma divergência entre a prosa e o schema —
  confirme com o time da Spedy se `invoice.contingency` já pode ser
  assinado como evento próprio antes de depender dele. Enquanto isso,
  `invoice.status_changed` cobre a transição para `inContingent` também.
</Note>

Cada webhook assina **um único evento** (campo `event` em `WebhookEditingDto`,
veja [Gerenciamento de webhooks](/pages/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](/pages/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).                                                                                       |
| `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}`). |

## 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](/pages/webhooks/visao-geral)) e `data.status` para
saber o estado atual da nota (veja [Ciclo de vida da
nota](/pages/guides/ciclo-de-vida-da-nota) para o significado de cada
valor).