Backend em Express

A rota que emite a credencial e o receptor de webhook, num servidor Express.

Quando o seu front não é Next.js, a rota é a mesma, só muda o framework.

Stack	Node 20 · Express 5
Você terá	uma rota que emite a credencial e um endpoint de webhook no mesmo servidor

Confira o exemplo

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

server.ts

import express from "express";

const app = express();

app.post("/api/verifications", express.json(), async (req, res) => {
  const user = await authenticate(req);
  if (!user) return res.status(401).json({ error: "not_authenticated" });

  const registration = await db.registration.byUser(user.id);

  const response = await fetch("https://api-core.legitimuz.com/public/verifications", {
    method: "POST",
    headers: {
      "X-API-Key": process.env.LEGITIMUZ_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      schema_version: "1.0",
      ref_id: registration.id,
      document: { type: "cpf", number: registration.cpf },
      flow_public_id: process.env.LEGITIMUZ_FLOW_ID!,
    }),
  });

  const { verification, entry } = await response.json();
  await db.registration.link(registration.id, verification.public_id);

  res.json({ entry });
});

// `raw`, não `json`: a conferência da assinatura precisa dos bytes originais.
app.post(
  "/api/webhooks/legitimuz",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    const rawBody = req.body.toString("utf8");
    const signature = req.get("X-Legitimuz-Signature") ?? "";

    if (!isSignatureValid(rawBody, signature, process.env.LEGITIMUZ_WEBHOOK_SECRET!)) {
      return res.sendStatus(401);
    }

    const isNew = await db.deliveries.recordIfNew(req.get("X-Legitimuz-Delivery")!);
    if (isNew) await queue.publish(JSON.parse(rawBody));

    res.sendStatus(200);
  }
);

app.listen(3000);

A ordem dos middlewares importa. Um express.json() global antes da rota de webhook consome o corpo e a conferência da assinatura passa a falhar sempre.

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.