Segurança

Confira a assinatura de cada entrega, descarte repetição e entenda a retentativa.

Todo POST chega assinado. Confira a assinatura antes de confiar no corpo: sem isso, quem descobrir a URL do seu endpoint consegue enviar um desfecho forjado.

Header

X-Legitimuz-Signature: t=1757865000,v1=5f2c8a1e...

Parte	O que é
t	o instante da assinatura, em segundos Unix
v1	o HMAC-SHA256 em hexadecimal

O HMAC é calculado com o segredo do endpoint sobre o timestamp, um ponto, e o corpo cru:

${timestamp}.${corpo cru}

Use o corpo cru, byte a byte, antes de qualquer parse. Reserializar o JSON muda os bytes e a conferência falha.

Como conferir

1. Extraia t e v1 do header.
2. Recuse se t estiver a mais de cinco minutos do relógio do seu servidor.
3. Recalcule o HMAC sobre ${t}.${corpo cru} com o segredo do endpoint.
4. Compare em tempo constante.

Node.js

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

export function assinaturaValida(corpoCru: string, header: string, segredo: string): boolean {
  const partes = Object.fromEntries(header.split(",").map((p) => p.split("=") as [string, string]));
  const timestamp = Number(partes.t);
  if (!timestamp || !partes.v1) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - timestamp) > 300) return false;

  const esperada = createHmac("sha256", segredo).update(`${timestamp}.${corpoCru}`).digest("hex");
  const a = Buffer.from(esperada, "utf8");
  const b = Buffer.from(partes.v1, "utf8");
  return a.length === b.length && timingSafeEqual(a, b);
}

Pegar o corpo cru

Express

app.post("/webhooks/legitimuz", express.raw({ type: "application/json" }), (req, res) => {
  const corpoCru = req.body.toString("utf8");
  if (!assinaturaValida(corpoCru, req.get("X-Legitimuz-Signature") ?? "", process.env.LEGITIMUZ_WEBHOOK_SECRET!)) {
    return res.sendStatus(401);
  }
  res.sendStatus(200);
});

No Express, declare express.raw() na própria rota. Um express.json() global antes dela consome o corpo.

Retentativa e idempotência

Se o seu servidor não responder 2xx, a entrega é tentada de novo em intervalos crescentes.

Tentativa	Espera
2ª	1 minuto
3ª	5 minutos
4ª	30 minutos
5ª	2 horas
6ª	6 horas

Depois disso a entrega é marcada como falha. O reenvio manual fica disponível na aba Webhooks da integração e de cada verificação.

Uma entrega pode chegar duas vezes. Descarte a repetição pelo header X-Legitimuz-Delivery:

const inedita = await db.entregas.registrarSeInedita(entregaId); // INSERT com chave única
if (!inedita) return res.sendStatus(200);

A ordem de chegada não é garantida. Se a ordem importa, use occurred_at do corpo.

Outros headers

Header	Para quê
X-Legitimuz-Event	o nome do evento
X-Legitimuz-Delivery	o identificador da entrega, a sua chave de idempotência
X-Legitimuz-Attempt	o número da tentativa

Rotacionar o segredo

Durante a rotação, aceite as duas assinaturas por uma janela curta e remova a antiga depois que as entregas em voo chegarem.

Próximo passo

Receptor completo

Uma POC com conferência, deduplicação e fila.