Receptor de webhook

O endpoint que recebe o desfecho: confere a assinatura, descarta repetição e enfileira o processamento.

O endpoint que recebe o desfecho. É a peça que mais dá errado, e a que mais importa acertar.

Stack	Node 20 · qualquer framework HTTP
Você terá	o endpoint que confere a assinatura, descarta repetição e enfileira

Confira o exemplo

Os arquivos desta POC, com o destino de cada um.

app/api/webhooks/legitimuz/route.ts

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

const TOLERANCE_SECONDS = 300;

export async function POST(request: Request) {
  // 1. CORPO CRU, antes de qualquer parse. Reserializar quebra a assinatura.
  const rawBody = await request.text();
  const signature = request.headers.get("x-legitimuz-signature") ?? "";
  const deliveryId = request.headers.get("x-legitimuz-delivery") ?? "";

  if (!isSignatureValid(rawBody, signature, process.env.LEGITIMUZ_WEBHOOK_SECRET!)) {
    return new Response(null, { status: 401 });
  }

  // 2. Descarte repetição. INSERT com chave única, não SELECT seguido de INSERT.
  const isNew = await db.deliveries.recordIfNew(deliveryId);
  if (!isNew) return new Response(null, { status: 200 });

  // 3. Enfileire e responda. Não processe dentro do request.
  await queue.publish(JSON.parse(rawBody));
  return new Response(null, { status: 200 });
}

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);
  const received = parts.v1;
  if (!timestamp || !received) return false;

  if (Math.abs(Math.floor(Date.now() / 1000) - timestamp) > TOLERANCE_SECONDS) return false;

  const expected = createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  const a = Buffer.from(expected, "utf8");
  const b = Buffer.from(received, "utf8");
  return a.length === b.length && timingSafeEqual(a, b);
}

Worker que processa

worker.ts

export async function processEvent(event: LegitimuzEnvelope) {
  // Evento desconhecido não derruba nada: registre e siga.
  if (event.event !== "verification.decided") return;

  const { status, ref_id } = event.verification;
  if (!ref_id) return;

  switch (status) {
    case "approved":
      await db.registration.approve(ref_id);
      break;
    case "reproved":
      await db.registration.reject(ref_id);
      break;
    case "review":
      // Não é recusa. Este evento dispara DE NOVO quando um analista decidir.
      await db.registration.markUnderReview(ref_id);
      break;
  }
}

Testar localmente

# 1. Exponha a porta local
npx untun tunnel http://localhost:3000

# 2. Cadastre a URL do túnel no dashboard, em Integrações → Segurança → Webhooks
# 3. Dispare a entrega de teste pelo próprio dashboard

Verificar a assinatura

O mesmo código em Python, PHP e Go.

Antes de rodar

.env

LEGITIMUZ_API_KEY=<SUA_CHAVE>
LEGITIMUZ_WEBHOOK_SECRET=<SEGREDO_DO_ENDPOINT>
LEGITIMUZ_FLOW_ID=<FLOW_PUBLIC_ID>

Variável	Onde achar
LEGITIMUZ_API_KEY	Integrações → Segurança → Chaves de API. Aparece uma vez
LEGITIMUZ_WEBHOOK_SECRET	Integrações → Segurança → Webhooks, na criação do endpoint
LEGITIMUZ_FLOW_ID	Solução KYC → Fluxos, no menu da linha, em Copiar ID do fluxo

Use uma integração sandbox. Nenhum dos três valores vai para o browser ou para o app.

O que esta POC não faz

POC é código para entender o fluxo, não para copiar em produção. Em todas elas, authenticate() é um stub, db é um objeto de mentira e não há migration, observabilidade nem retentativa própria.

• Migrations e schema do banco.
• Observabilidade e alerta.
• Tela de retomada quando o titular abandona e volta. Veja a POC de retomada.

Próximo passo

Boas práticas

O que separa uma integração que funciona de uma que gera chamado.

Ir para produção

O checklist antes do primeiro titular real.