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

# Webhooks: visão geral

> Visão geral do sistema de webhooks da Spedy.

A emissão de notas fiscais na Spedy é **assíncrona**: quando você emite uma
nota, a resposta `2xx` confirma apenas que a solicitação foi aceita para
processamento — não que ela foi autorizada pela SEFAZ ou pela prefeitura. O
`status` evolui em segundo plano até um estado final (`authorized`,
`rejected` etc.). Veja [Ciclo de vida da
nota](/pages/guides/ciclo-de-vida-da-nota) para a máquina de estados
completa.

Webhooks são a forma recomendada de acompanhar essas transições: em vez de o
seu sistema perguntar repetidamente "já autorizou?" (*polling*), a Spedy
avisa proativamente com um HTTP POST assim que o evento acontece.

## Por que usar webhooks em vez de polling

* **Menos latência.** Você é notificado no momento em que o status muda, em
  vez de esperar o próximo ciclo de consulta.
* **Menos carga.** Elimina chamadas repetidas a `GET /v1/{modelo}-invoices/{id}`
  só para verificar se algo mudou — a maioria delas retornaria "sem
  novidade".
* **Menos código de orquestração.** Seu sistema reage a eventos em vez de
  manter um scheduler de consultas para cada nota em andamento.

<Note>
  Webhooks não substituem totalmente a consulta por API. Entregas podem
  falhar ou, no limite, o webhook pode ser desabilitado após esgotar as
  retentativas (veja [Gerenciamento de
  webhooks](/pages/webhooks/gerenciamento)). Trate os endpoints de consulta
  como a fonte de verdade para reconciliação.
</Note>

## Webhook é por conta, não por empresa

Um webhook é configurado **uma vez por conta**, não por empresa. Uma única
configuração recebe eventos de **todas as empresas** cadastradas na conta —
não é necessário (nem possível) criar um webhook separado para cada CNPJ.

Para identificar qual empresa gerou um evento recebido, use o objeto
`company` presente no `data` do payload (veja [Eventos e
payload](/pages/webhooks/eventos-e-payload)).

## Como começar

1. Escolha os [eventos](/pages/webhooks/eventos-e-payload) que interessam à
   sua integração — na maioria dos casos, `invoice.status_changed` sozinho já
   cobre todo o ciclo de vida da nota.
2. Crie o webhook via `POST /v1/webhooks`, informando `event` e `url`. Veja
   os exemplos em [Gerenciamento de webhooks](/pages/webhooks/gerenciamento).
3. Implemente o endpoint que recebe o POST e responda `2xx` rapidamente.
4. Trate a entrega como best-effort: eventos podem chegar fora de ordem ou,
   em cenários raros, não chegar. Reconcilie pelo `status` da nota
   consultando os endpoints de leitura (`GET` na nota) e deduplique pelo `id`
   do evento.

<CardGroup cols={2}>
  <Card title="Gerenciamento de webhooks" icon="gear" href="/pages/webhooks/gerenciamento">
    Crie, edite, desabilite e reative webhooks via API. Política de retry.
  </Card>

  <Card title="Eventos e payload" icon="list-check" href="/pages/webhooks/eventos-e-payload">
    Tipos de evento disponíveis e o formato completo do payload.
  </Card>
</CardGroup>