Webhooks & Notificações Assíncronas

Em emissões fiscais em lote, contingência ou consultas assíncronas da SEFAZ, o uso de Webhooks permite que a sua aplicação receba notificações imediatas assim que um documento é processado.

---

Eventos Suportados

Evento	Gatilho
invoice.authorized	Documento fiscal (NF-e, NFC-e ou NFS-e) autorizado com sucesso.
invoice.rejected	Documento fiscal rejeitado pela SEFAZ ou prefeitura com detalhes de erro.
invoice.cancelled	Evento de cancelamento homologado pelo órgão emissor.
certificate.expiring	Alerta de que o certificado A1 expira em menos de 30 dias.

---

Verificação de Assinatura do Webhook (Segurança)

Toda notificação HTTP POST enviada pela API para a URL do seu webhook inclui um cabeçalho de assinatura criptográfica HMAC-SHA256:

X-Webhook-Signature: sha256=d6a89c8a98...

Validando a Assinatura no seu Backend

Node.js (TypeScript)

import crypto from 'crypto';

function verifyWebhook(payload: string, signature: string, secret: string): boolean {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = 'sha256=' + hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(digest));
}

Python

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature, expected)

---

Política de Retentativas (Retry Policy)

Caso o seu endpoint de webhook retorne códigos 5xx ou ocorra timeout:

• A API realizará até 5 tentativas com backoff exponencial (1min, 5min, 15min, 1h, 6h).
• O payload de cada tentativa mantém o mesmo identificador de evento para evitar duplicidade no seu sistema.