ConceitosWebhooks

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.

POST /v1/webhooks
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"]  }'
201 Created
{  "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.autorizada
    A nota foi aceita e ganhou número e chave de acesso
  • nfse.rejeitada
    A nota foi recusada na transmissão
  • nfse.cancelada
    O cancelamento de uma nota foi confirmado
  • guia.disponivel
    Uma guia nova, como o DAS do mês, foi gerada para a empresa
  • guia.vencendo
    Faltam 3 dias para o vencimento de uma guia em aberto
  • guia.paga
    O pagamento de uma guia foi identificado
  • certificado.vencendo
    O 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.

POST https://seusistema.com.br/webhooks/emissor
{  "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.

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

Calcule o HMAC sobre os bytes recebidos, antes de converter o JSON. Reordenar ou reformatar o corpo muda a assinatura.

Respostas e novas tentativas

Responda com qualquer status 2xx em até 10 segundos. Fora disso, a entrega é considerada falha e repetida nestes intervalos:

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