Atendimento

Webhooks

Receba um POST assinado a cada mudança de status de uma nota.

A sua conta pode ter um endpoint HTTPS que recebe um POST a cada mudança de status de qualquer nota (NFS-e, NF-e ou NFC-e) de qualquer emitente da conta, inclusive a entrada da NFC-e em CONTINGENCIA. Com ele, você não precisa consultar as notas em loop.

Configurando

PUT /api/v1/conta/webhook
{ "url": "https://seu-sistema.example/webhooks/u2d-nota-fiscal" }
{
  "url": "https://seu-sistema.example/webhooks/u2d-nota-fiscal",
  "ativo": true,
  "segredo": "whsec_...",
  "criadoEm": "2026-11-14T10:00:00-03:00",
  "atualizadoEm": "2026-11-14T10:00:00-03:00"
}
  • O segredo só aparece na criação e na rotação (PUT /conta/webhook?rotacionarSegredo=true). Guarde-o como senha: é com ele que você confere a assinatura.
  • A URL precisa ser https (senão 400). Use "ativo": false para pausar as entregas.
  • GET /conta/webhook mostra a configuração sem o segredo (404 webhook-nao-configurado se não houver); DELETE /conta/webhook remove, e as entregas pendentes viram FALHOU.
  • POST /conta/webhook/teste enfileira um evento ping para validar o seu endpoint.

O evento

POST /webhooks/u2d-nota-fiscal
Content-Type: application/json
X-U2D-Evento: nfe.status_alterado
X-U2D-Evento-Id: 7d9f3b2a-1c4e-4a8b-9f6d-2e0c5a7b1d3f
X-U2D-Assinatura: t=1794744000,v1=5f2b8c...
{
  "id": "7d9f3b2a-1c4e-4a8b-9f6d-2e0c5a7b1d3f",
  "evento": "nfe.status_alterado",
  "ocorridoEm": "2026-11-14T10:00:03-03:00",
  "contaId": "6f1c2a9e-3b7d-4c1e-9a2f-5d8e7b6c4a10",
  "documento": {
    "tipo": "NFE",
    "id": "0b8e1c2a-7f3d-4c1e-9b2f-8d6a0e4c7b21",
    "emitenteId": "8b3c1f0e-5d2a-4a1b-9c3d-2e1f0a9b8c7d",
    "status": "AUTORIZADA",
    "ambiente": "HOMOLOGACAO",
    "serie": "1",
    "numero": 42,
    "chaveAcesso": "53261111222333000181550010000000421000000420",
    "numeroNfse": null
  }
}

Eventos: nfse.status_alterado, nfe.status_alterado, nfce.status_alterado e ping. O payload é enxuto: para os detalhes (erros, totais, protocolo), faça o GET da nota.

Conferindo a assinatura

X-U2D-Assinatura traz t (epoch em segundos) e v1 = HMAC-SHA256(segredo, "<t>.<corpo bruto>") em hexadecimal.

import { createHmac, timingSafeEqual } from "node:crypto";

function assinaturaValida(corpoBruto, cabecalho, segredo) {
  const partes = Object.fromEntries(cabecalho.split(",").map((parte) => parte.split("=")));
  const idadeSegundos = Math.abs(Date.now() / 1000 - Number(partes.t));
  if (!partes.t || !partes.v1 || idadeSegundos > 300) return false;
  const esperado = createHmac("sha256", segredo).update(`${partes.t}.${corpoBruto}`).digest("hex");
  return timingSafeEqual(Buffer.from(esperado), Buffer.from(partes.v1));
}
  • Use o corpo bruto, exatamente como chegou, antes de qualquer parse de JSON.
  • Compare em tempo constante e recuse t antigo (mais de 5 minutos), para barrar reenvio de evento capturado.

Entrega

  • Sucesso é qualquer 2xx em até 10 segundos. Redirect não é seguido.
  • Ao menos uma vez: o mesmo evento pode chegar mais de uma vez. Deduplique pelo id (igual a X-U2D-Evento-Id).
  • Sem garantia de ordem: use ocorridoEm e, na dúvida, o GET da nota.
  • Responda rápido e processe depois, numa fila do seu lado.

Em falha, a entrega é repetida em 1, 2, 4... minutos (até 24 horas entre tentativas), em até 10 tentativas, e depois fica FALHOU.

RotaPara quê
GET /conta/webhook/entregas?status=entregas PENDENTE, ENTREGUE ou FALHOU, com tentativas, ultimoHttpStatus, ultimoErro e o payload
POST /conta/webhook/entregas/{id}/reenviarpõe a entrega de volta na fila, com as tentativas zeradas

Nesta página