Webhooks NF-e / NFC-e

Receba notificações em tempo real sobre o ciclo de vida das suas NF-e e NFC-e. Os mesmos endpoints de gerenciamento da NFS-e ( /webhooks/endpoints ) suportam eventos NF-e/NFC-e. Cadastre os eventos desejados ao criar ou atualizar um endpoint.

Eventos Suportados

NF-e (modelo 55)

Eventos NF-e

Campo	Tipo	Req?	Descrição
nfe.issued	event	não	NF-e autorizada pela SEFAZ (cStat 100 ou 150). Payload inclui invoiceId, chaveAcesso, nProt, cStat, xMotivo.
nfe.error	event	não	Rejeição SEFAZ na emissão. Payload inclui invoiceId, chaveAcesso, cStat, xMotivo.
nfe.cancelled	event	não	NF-e cancelada com sucesso na SEFAZ. Payload inclui invoiceId, chaveAcesso, nProt.

NFC-e (modelo 65)

Eventos NFC-e

Campo	Tipo	Req?	Descrição
nfce.issued	event	não	NFC-e autorizada pela SEFAZ. Payload inclui invoiceId, chaveAcesso, nProt, cStat, xMotivo, qrCode (URL do QR Code) e urlChave (consulta pública SEFAZ).
nfce.error	event	não	Rejeição SEFAZ na emissão NFC-e. Payload inclui invoiceId, chaveAcesso, cStat, xMotivo.
nfce.cancelled	event	não	NFC-e cancelada com sucesso. Payload inclui invoiceId, chaveAcesso, nProt.

Formato do Payload

Todos os eventos são enviados via POST com Content-Type: application/json. O header X-Notaas-Event identifica o tipo do evento.

{
  "event": "nfe.issued",
  "deliveryId": "uuid",
  "timestamp": "2026-04-22T19:30:00Z",
  "data": {
    "invoiceId": "uuid-da-nfe",
    "chaveAcesso": "41260412345678000195550010000000011234567890",
    "nProt": "141260000012345",
    "cStat": 100,
    "xMotivo": "Autorizado o uso da NF-e",
    "dhRecbto": "2026-04-22T19:30:00-03:00"
  }
}

Verificação de Assinatura

Se um secret estiver configurado no endpoint, o header X-Notaas-Signature conterá o HMAC-SHA256 do body usando o secret como chave.

// Validação em Node.js
const crypto = require('crypto');

function verifySignature(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body, 'utf8')
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Retentativas

Em caso de falha (status ≥ 400 ou timeout), o sistema faz até 5 retentativas com backoff exponencial:

Tentativa	Intervalo
1	Imediata
2	1 minuto
3	5 minutos
4	30 minutos
5	2 horas