---
title: "Webhooks"
description: "Receba eventos da API do Emissor de Nota por webhook: cadastro do endpoint, lista de eventos, formato da entrega, assinatura HMAC-SHA256 e novas tentativas."
url: https://docs.emissordenota.com/webhooks
language: pt-BR
---
# 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**

```bash
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**

```json
{
  "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

| Evento | Quando 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**

```json
{
  "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**

```javascript
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:

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