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
segredosó 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ão400). Use"ativo": falsepara pausar as entregas. GET /conta/webhookmostra a configuração sem o segredo (404 webhook-nao-configuradose não houver);DELETE /conta/webhookremove, e as entregas pendentes viramFALHOU.POST /conta/webhook/testeenfileira um eventopingpara 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
tantigo (mais de 5 minutos), para barrar reenvio de evento capturado.
Entrega
- Sucesso é qualquer
2xxem até 10 segundos. Redirect não é seguido. - Ao menos uma vez: o mesmo evento pode chegar mais de uma vez. Deduplique pelo
id(igual aX-U2D-Evento-Id). - Sem garantia de ordem: use
ocorridoEme, na dúvida, oGETda 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.
| Rota | Para quê |
|---|---|
GET /conta/webhook/entregas?status= | entregas PENDENTE, ENTREGUE ou FALHOU, com tentativas, ultimoHttpStatus, ultimoErro e o payload |
POST /conta/webhook/entregas/{id}/reenviar | põe a entrega de volta na fila, com as tentativas zeradas |