Webhooks: visão geral

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

​

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

​

Como começar

1. Escolha os eventos 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.
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.