Segurança - Legitimuz

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.

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}.${rawBody}

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

Como conferir

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

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

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

  const expected = createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
  const a = Buffer.from(expected, "utf8");
  const b = Buffer.from(parts.v1, "utf8");
  return a.length === b.length && timingSafeEqual(a, b);
}

import hashlib, hmac, time

def is_signature_valid(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    try:
        timestamp = int(parts["t"]); received = parts["v1"]
    except (KeyError, ValueError):
        return False
    if abs(int(time.time()) - timestamp) > 300:
        return False
    expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, received)

<?php
function isSignatureValid(string $rawBody, string $header, string $secret): bool
{
    $parts = [];
    foreach (explode(',', $header) as $p) { [$k, $v] = array_pad(explode('=', $p, 2), 2, null); $parts[$k] = $v; }
    if (empty($parts['t']) || empty($parts['v1'])) return false;
    if (abs(time() - (int) $parts['t']) > 300) return false;
    $expected = hash_hmac('sha256', $parts['t'] . '.' . $rawBody, $secret);
    return hash_equals($expected, $parts['v1']);
}

func isSignatureValid(rawBody []byte, header, secret string) bool {
	parts := map[string]string{}
	for _, p := range strings.Split(header, ",") {
		if k, v, ok := strings.Cut(p, "="); ok { parts[k] = v }
	}
	ts, err := strconv.ParseInt(parts["t"], 10, 64)
	if err != nil || parts["v1"] == "" { return false }
	if d := time.Now().Unix() - ts; d > 300 || d < -300 { return false }
	mac := hmac.New(sha256.New, []byte(secret))
	fmt.Fprintf(mac, "%d.", ts); mac.Write(rawBody)
	return hmac.Equal([]byte(hex.EncodeToString(mac.Sum(nil))), []byte(parts["v1"]))
}

Pegar o corpo cru

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

export async function POST(request: Request) {
  const rawBody = await request.text();
  if (!isSignatureValid(rawBody, request.headers.get("x-legitimuz-signature") ?? "", process.env.LEGITIMUZ_WEBHOOK_SECRET!)) {
    return new Response(null, { status: 401 });
  }
  return new Response(null, { status: 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 isNew = await db.deliveries.recordIfNew(deliveryId); // INSERT com chave única
if (!isNew) 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

Trocar o segredo

O signing_secret sai uma vez só, na criação do endpoint, e não há rotação: nem no dashboard, nem na API. Trocar o segredo é criar um endpoint novo com a mesma URL e remover o antigo depois. Enquanto os dois existirem, aceite as duas assinaturas.

Aceitar dois segredos durante a troca

const secrets = [process.env.LEGITIMUZ_WEBHOOK_SECRET!, process.env.LEGITIMUZ_WEBHOOK_SECRET_PREVIOUS]
  .filter((s): s is string => Boolean(s));

const isValid = secrets.some((secret) => isSignatureValid(rawBody, header, secret));

Nessa janela cada evento chega duas vezes, uma por endpoint, e as duas entregas têm X-Legitimuz-Delivery diferente — a chave de idempotência da retentativa não descarta a cópia do outro endpoint. Deduplique pelo par verificação + evento enquanto os dois existirem.

Remova LEGITIMUZ_WEBHOOK_SECRET_PREVIOUS e o endpoint antigo depois que as entregas em voo chegarem. O passo a passo no dashboard está em trocar o segredo de um endpoint.

Próximo passo

Receptor completo

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

​Header

​Como conferir

​Pegar o corpo cru

​Retentativa e idempotência

​Outros headers

​Trocar o segredo

​Próximo passo

Receptor completo

Header

Como conferir

Pegar o corpo cru

Retentativa e idempotência

Outros headers

Trocar o segredo

Próximo passo