🔔 Eventos Assíncronos (Webhooks)

Várias operações financeiras dependem de confirmação de redes externas (Pix, blockchain, compliance) e não ocorrem instantaneamente. A DEX API envia notificações automáticas do tipo push para o seu servidor quando ocorrem atualizações.

Analogia: É como o rastreamento de uma entrega. Em vez de entrar no site da transportadora a cada 5 minutos, você recebe um SMS avisando que o pacote foi entregue.

O Que É um Webhook?

Um webhook é apenas um endpoint do seu servidor (uma URL POST) que você cadastra no Painel do Participante ou na interface do usuário (no caso de contas pessoais).

1. Dicionário de Eventos Comuns

• PIX_DEPOSIT_COMPLETED: Um depósito via Pix foi recebido e creditado.

• PIX_WITHDRAW_COMPLETED: Um saque via Pix foi liquidado no Banco Central.

• PIX_WITHDRAW_FAILED: O saque Pix falhou e foi estornado.

• KYC_APPROVED: A verificação de documentos cadastrais do usuário foi aprovada.

• KYC_REJECTED: Documentos rejeitados pelo time de compliance (requer reenvio).

• ACCOUNT_UPGRADED_TO_FULL: O usuário foi promovido ao nível FULL e pode transacionar.

• CRYPTO_DEPOSIT_CONFIRMED: Depósito em criptomoeda recebido e minerado na blockchain.

2. Formato do Envelope JSON

Todas as notificações chegam na sua URL com a mesma estrutura:

{
  "id": "0df83749-d7b8-4d56-8c43-1e5828453cc1",
  "event": "PIX_WITHDRAW_COMPLETED",
  "timestamp": "2026-06-17T15:00:00.000Z",
  "data": {
    "transactionId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "COMPLETED",
    "amount": 10000
  }
}

Cada chamada inclui o cabeçalho X-Signature para validação HMAC.

3. Validação de Assinatura (Segurança HMAC)

Para garantir que a notificação foi enviada pela Ether (e não por um invasor simulando depósitos), você deve validar a assinatura usando o seu Webhook Secret:

1. Extraia o timestamp t e o hash v1 do cabeçalho X-Signature (ex: t=1718640000,v1=a1b2c3d...).

2. Concatene em string: t.X-Delivery-Id.Corpo_JSON_Cru (separados por ponto).

3. Gere um hash HMAC-SHA256 usando seu Webhook Secret.

4. Compare com a assinatura v1 recebida. Rejeite assinaturas com mais de 5 minutos de diferença (proteção anti-replay).

Exemplo: Servidor Webhook Mínimo (Node.js/Express)

Selecione abaixo para visualizar um exemplo funcional completo de servidor para receber e autenticar webhooks de forma segura:

💻 Ver Código do Servidor Exemplo

import express from 'express';
import crypto from 'crypto';

const app = express();
app.use(express.raw({ type: 'application/json' }));

const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET || 'seu_secret';

function validar(body: Buffer, deliveryId: string, signature: string): boolean {
  const partes = signature.split(',');
  const timestamp = partes[0]?.replace('t=', '');
  const hash = partes[1]?.replace('v1=', '');

  if (!timestamp || !hash) return false;

  const agora = Math.floor(Date.now() / 1000);
  if (Math.abs(agora - Number(timestamp)) > 300) return false; // Replay protect

  const payload = `${timestamp}.${deliveryId}.${body.toString()}`;
  const hashEsperado = crypto.createHmac('sha256', WEBHOOK_SECRET).update(payload).digest('hex');

  return crypto.timingSafeEqual(Buffer.from(hash, 'hex'), Buffer.from(hashEsperado, 'hex'));
}

app.post('/webhooks/dex', (req, res) => {
  const deliveryId = req.headers['x-delivery-id'] as string;
  const signature = req.headers['x-signature'] as string;

  if (!validar(req.body, deliveryId, signature)) {
    return res.status(401).send('Assinatura inválida');
  }

  const evento = JSON.parse(req.body.toString());
  console.log(`Evento recebido: ${evento.event}`);
  res.status(200).send('OK');
});

app.listen(3001);