Eventos e payload

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

invoice.contingency está documentado na descrição do endpoint POST /v1/webhooks e na seção de Contingência 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.

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).
`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.

{
  "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).

​Eventos disponíveis

​Envelope do payload

​Exemplo de payload

Eventos disponíveis

Envelope do payload

Exemplo de payload