Webhooks: Visão Geral e Arquitetura
Notificações em tempo real, quando usar webhooks vs polling e ciclo de entrega.
Os Webhooks da NFER são a espinha dorsal de qualquer integração moderna de faturamento. Em vez de seu ERP, e-commerce ou backend consultar repetidamente a API para saber se uma nota foi autorizada (polling), a NFER envia uma notificação HTTP POST em tempo real para a URL do seu servidor com o payload completo do evento assinado criptograficamente.
Tempo Real
No instante exato em que a SEFAZ ou prefeitura processa o documento, o evento é despachado com a chave de 44 dígitos e o protocolo.
Assinatura HMAC
Cada entrega carrega o cabeçalho X-NFER-Signature calculado via SHA256 com sua chave secreta única.
Entrega Resiliente
Fila BullMQ com até 8 tentativas de entrega com backoff exponencial durante 2 horas em caso de instabilidade no seu servidor.
Quando Usar Webhooks × Polling
Recomendamos fortemente a arquitetura Webhook-First para todos os clientes em produção. Veja o comparativo:
| Critério | Webhooks NFER (Recomendado) | Polling Periódico (GET /v1/nfe/:id) |
|---|---|---|
| Latência de Notificação | Sub-segundo (~50ms a 300ms após autorização). | Depende do intervalo de consulta (ex: a cada 5s ou 10s). |
| Consumo de Rate Limit | Zero consumo das suas cotas de requisição HTTP. | Consome chamadas contínuas contra a cota da sua API Key. |
| Carga no seu Servidor | Recebe apenas requisições quando algo de fato acontece. | Gera overhead constante de loops e timers em background. |
| Tratamento de Desconexão | NFER armazena os eventos na fila e reenvia automaticamente. | Se o processo de polling cair, o estado pode se perder. |
Quando o polling ainda é útil?
Ciclo de Vida de uma Notificação
A SEFAZ ou prefeitura autoriza, cancela ou rejeita o documento. A NFER gera um identificador único de entrega (X-NFER-Delivery) e monta o payload canônico.
O motor de webhook calcula o hash HMAC-SHA256 do corpo da mensagem com o segredo do endpoint cadastrado e insere o timestamp anti-replay.
A requisição é enviada para a sua URL cadastrada. Seu servidor deve responder com status HTTP 2xx dentro de no máximo 15 segundos.
Se a resposta for 200 OK, a entrega é marcada como sucesso. Se o servidor retornar 5xx ou timeout, o BullMQ agenda retentativa automática.