Fila e worker

Responda 2xx em milissegundos e processe o desfecho fora do request, com retentativa própria.

O endpoint de webhook tem um trabalho só: conferir a assinatura e aceitar. Tudo o que demora — liberar cadastro, chamar antifraude interno, mandar e-mail — acontece depois, num worker.

Stack	Node 20 · BullMQ · Redis
Você terá	um endpoint que responde em milissegundos e um worker com retentativa própria

Confira o exemplo

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

Por que separar

A Legitimuz reentrega o que não responde 2xx, em intervalos crescentes. Se o seu handler processa dentro do request, dois problemas aparecem juntos: uma tarefa lenta vira timeout e a entrega é reenviada; e o seu retry passa a ser o retry da Legitimuz, que não conhece o seu banco.

Separar deixa cada lado com a retentativa que ele entende.

O endpoint

app/api/webhooks/legitimuz/route.ts

import { outcomeQueue } from "@/lib/queues";

export async function POST(request: Request) {
  const rawBody = await request.text();
  const deliveryId = request.headers.get("x-legitimuz-delivery") ?? "";

  if (!isSignatureValid(rawBody, request.headers.get("x-legitimuz-signature") ?? "")) {
    return new Response(null, { status: 401 });
  }

  // `jobId` é a chave de idempotência: a fila recusa o mesmo id e a reentrega vira no-op.
  await outcomeQueue.add("outcome", JSON.parse(rawBody), {
    jobId: deliveryId,
    attempts: 5,
    backoff: { type: "exponential", delay: 1_000 },
    removeOnComplete: 1_000,
  });

  return new Response(null, { status: 200 });
}

O jobId substitui a tabela de deduplicação das outras POCs. Um id só existe uma vez na fila, então a segunda entrega do mesmo evento não cria um segundo job.

O worker

workers/outcome.ts

import { Worker } from "bullmq";

new Worker(
  "outcome",
  async (job) => {
    const event = job.data;

    if (event.event !== "verification.decided") return;

    const registration = await db.registrations.byRefId(event.verification.ref_id);
    if (!registration) throw new Error(`no registration for ref_id: ${event.verification.ref_id}`);

    // `review` não é recusa: a verificação volta a decidir depois, e este mesmo evento chega de novo.
    if (event.verification.status === "review") {
      await db.registrations.markUnderReview(registration.id);
      return;
    }

    await db.registrations.applyOutcome(registration.id, event.verification.status);
  },
  { connection: { host: process.env.REDIS_HOST, port: 6379 }, concurrency: 5 },
);

Lançar dentro do worker é o caminho certo de erro: o BullMQ conta a tentativa e reprograma. Um try/catch que engole a exceção marca o job como concluído e o desfecho se perde em silêncio.

Ordem não é garantida

Dois eventos da mesma verificação podem chegar fora de ordem. Se a sua lógica depende disso, use o occurred_at do corpo e descarte o que for mais antigo que o estado já gravado:

Ignorar evento atrasado

const atual = await db.registrations.byRefId(event.verification.ref_id);

if (atual.outcome_at && new Date(event.occurred_at) < atual.outcome_at) return;

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.

Esta POC precisa também de um Redis:

.env

REDIS_HOST=localhost

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.

• Sem dead-letter queue. Depois de 5 tentativas o job fica em failed e ninguém é avisado.
• Sem métrica de profundidade da fila.
• Sem lock por ref_id: dois eventos da mesma verificação podem rodar em paralelo.

Próximo passo

Receptor de webhook

A conferência da assinatura, linha a linha.

Retomada e expiração

O que fazer quando o titular some no meio.