Skip to main content
Webhooks são entregues por endpoint configurado na empresa, assinados com HMAC-SHA256, de forma assíncrona — a entrega HTTP nunca bloqueia a requisição nem a transição de estado.
Webhooks cobrem a NF-e (eventos nfe_*). A NFS-e é acompanhada por polling em GET /notas/{id} — veja o Ciclo de vida.

​
Verificação de assinatura

Cada entrega traz dois cabeçalhos: A string canônica assinada é o X-Webhook-Timestamp, um ponto (.) e o corpo bruto do POST, concatenados:
Recompute o HMAC-SHA256 dessa string com a chave_seguranca do endpoint e compare com X-Webhook-Signature usando uma comparação de tempo constante (ex.: Rack::Utils.secure_compare) — nunca uma igualdade simples de string, que vaza informação por timing. O timestamp na string assinada também permite rejeitar entregas antigas (proteção contra replay).

​
Semântica de entrega

A entrega é não ordenada e at-least-once (pelo menos uma vez): há um job independente por endpoint, com retries independentes. Portanto:
  • a ordem entre eventos não é garantida (um nfe_autorizada rápido pode chegar antes de um nfe_solicitacao_autorizacao que sofreu retry);
  • o mesmo evento pode ser entregue mais de uma vez.
Cada payload carrega event_id (UUID estável entre retries) e occurred_at (instante do evento). Os consumidores devem:
1

Deduplicar por event_id

Ignore um event_id já processado.
2

Ignorar eventos mais antigos

Descarte eventos com occurred_at anterior ao último já aplicado para aquela nota.

​
Tipos de evento (nfe_*)

​
nfe_inutilizada tem dois formatos de payload

O evento nfe_inutilizada cobre os dois modos de inutilização, com payloads distintos. Diferencie pelo campo modo ("nota" ou "faixa") — todos os payloads carregam modo, então você nunca precisa inferir o formato pela presença de campos:
  • Modo nota ("modo": "nota") — carrega uuid e chave_acesso (uma nota específica).
  • Modo faixa ("modo": "faixa") — carrega numero_inicial e numero_final (uma faixa de numeração, sem nota associada).
As URLs de xml_url / danfe_url são as rotas autenticadas da API (Basic auth), nunca links públicos a documentos fiscais.