Webhooks
Seu servidor é avisado quando uma nota é autorizada, uma guia fica disponível ou um certificado está para vencer. Assim você não precisa ficar consultando a API.
Cadastre um endpoint
Pelo painel, em Configurações › API e integrações, ou pela API. O endereço precisa ser HTTPS.
curl -X POST https://api.emissordenota.com/v1/webhooks \ -H "Authorization: Bearer $EDN_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://seusistema.com.br/webhooks/emissor", "eventos": ["nfse.autorizada", "nfse.rejeitada", "guia.disponivel"] }'{ "id": "wh_5Rk8sNc2Yd", "url": "https://seusistema.com.br/webhooks/emissor", "eventos": ["nfse.autorizada", "nfse.rejeitada", "guia.disponivel"], "segredo": "whsec_Tz4Lm9Qx2Vb7Kc1Nw8Ry5Pd3", "ativo": true}O segredo aparece só nesta resposta. Guarde-o para conferir a assinatura das entregas.
Eventos
EventoQuando dispara
- nfse.autorizadaA nota foi aceita e ganhou número e chave de acesso
- nfse.rejeitadaA nota foi recusada na transmissão
- nfse.canceladaO cancelamento de uma nota foi confirmado
- guia.disponivelUma guia nova, como o DAS do mês, foi gerada para a empresa
- guia.vencendoFaltam 3 dias para o vencimento de uma guia em aberto
- guia.pagaO pagamento de uma guia foi identificado
- certificado.vencendoO certificado A1 de uma empresa vence em 30 dias
Formato da entrega
Cada evento é um POST com corpo JSON. O campo dados traz o mesmo objeto que a API devolve na consulta do recurso.
{ "id": "evt_2Vn6cXp9Lt", "evento": "guia.disponivel", "criado_em": "2026-11-05T08:00:14-03:00", "empresa_id": "emp_8Kq2mXv41c", "dados": { "id": "guia_9Wd3kRs6Ph", "tipo": "das", "competencia": "2026-10", "valor": 1284.37, "vencimento": "2026-11-20", "pdf_url": "https://api.emissordenota.com/v1/guias/guia_9Wd3kRs6Ph/pdf" }}Confira a assinatura
Toda entrega leva o cabeçalho X-Emissor-Assinatura com o HMAC-SHA256 do corpo, calculado com o segredo do endpoint. Recalcule e compare antes de confiar no conteúdo.
const crypto = require("crypto");function assinaturaValida(corpoBruto, cabecalho, segredo) { const esperado = crypto .createHmac("sha256", segredo) .update(corpoBruto) .digest("hex"); return crypto.timingSafeEqual( Buffer.from(esperado), Buffer.from(cabecalho) );}Assine o corpo bruto
Respostas e novas tentativas
Responda com qualquer status 2xx em até 10 segundos. Fora disso, a entrega é considerada falha e repetida nestes intervalos:
| Tentativa | Quando |
|---|---|
| 1ª | Na hora do evento |
| 2ª | 1 minuto depois |
| 3ª | 5 minutos depois |
| 4ª | 30 minutos depois |
| 5ª | 2 horas depois |
| 6ª | 12 horas depois |
Depois da sexta falha seguida, o endpoint é pausado e os administradores do escritório recebem um e-mail. Reative pelo painel quando o problema estiver resolvido.
Boas práticas
- Responda rápido e processe depois, numa fila.
- O mesmo evento pode chegar mais de uma vez. Guarde o id do evento e ignore os repetidos.
- A ordem de chegada não é garantida. Use criado_em para saber o que é mais recente.
- Acompanhe as entregas e reenvie as que falharam em Configurações › API e integrações.