Construindo um Listener de Webhook Didit com Fastify e PostgreSQL (PT-BR)

Integração Segura de WebhookA implementação da verificação de assinatura HMAC-SHA256 é crucial para garantir a autenticidade e integridade das cargas de webhook do Didit, protegendo sua aplicação contra solicitações falsificadas e mantendo a segurança dos dados.

Processamento de Dados em Tempo RealUtilize webhooks para receber notificações instantâneas sobre mudanças no status da sessão de verificação de identidade, permitindo que sua aplicação reaja imediatamente e automatize fluxos de trabalho de integração de usuários ou gerenciamento de riscos.

Armazenamento de Dados EscalávelAproveite o PostgreSQL para armazenar e gerenciar eficientemente os dados do webhook, permitindo consultas robustas, auditoria e integração com seus sistemas de gerenciamento de usuários existentes, garantindo a persistência e confiabilidade dos dados.

A Vantagem Modular do DiditA plataforma de identidade modular do Didit e o sistema abrangente de webhooks simplificam a integração, fornecendo aos desenvolvedores APIs limpas e fluxos de dados em tempo real para construir soluções KYC flexíveis e nativas de IA com KYC Core Gratuito e sem taxas de configuração.

Compreendendo os Webhooks do Didit e Sua Importância

No mundo da verificação de identidade, o feedback em tempo real é primordial. Seja você integrando novos usuários, prevenindo fraudes ou garantindo conformidade, saber o status de uma sessão de verificação no momento em que ela acontece é crítico. É aqui que entram os webhooks. Os webhooks do Didit fornecem uma maneira automatizada de receber notificações sobre eventos que ocorrem em seus fluxos de trabalho de verificação de identidade, como uma sessão sendo concluída, falhando ou exigindo ações adicionais.

Em vez de constantemente pesquisar a API do Didit por atualizações, o que pode ser ineficiente e levar a atrasos, os webhooks enviam dados diretamente para seu endpoint configurado. Essa arquitetura orientada a eventos garante que sua aplicação sempre tenha as informações mais atualizadas, permitindo processamento imediato e uma experiência de usuário mais fluida. Por exemplo, uma vez que um usuário conclui com sucesso a Verificação de ID e as verificações de Prova de Vida Passiva e Ativa do Didit, um webhook pode acionar a próxima etapa em seu fluxo de integração instantaneamente.

O Didit oferece versões configuráveis de webhook, sendo a v3 o padrão recomendado por sua estrutura de payload abrangente. Você pode definir sua URL de webhook, versão e até mesmo políticas de retenção de dados diretamente através do Didit Business Console ou via API, dando-lhe controle total sobre seu fluxo de dados e obrigações de conformidade.

Configurando Seu Listener de Webhook Fastify

Fastify é um framework web rápido e de baixa sobrecarga para Node.js, tornando-o uma excelente escolha para construir listeners de webhook de alto desempenho. Veja como começar:

1. Configuração do Projeto e Dependências

Primeiro, inicialize seu projeto Node.js e instale os pacotes necessários:

mkdir didit-webhook-listener
cd didit-webhook-listener
npm init -y
npm install fastify dotenv pg crypto

Crie um arquivo .env para armazenar sua chave secreta de webhook do Didit e detalhes de conexão do PostgreSQL:

DIDIT_WEBHOOK_SECRET=sua_chave_secreta_webhook_didit
DATABASE_URL=postgresql://usuario:senha@host:porta/banco_de_dados

Você pode recuperar seu DIDIT_WEBHOOK_SECRET no Didit Business Console em Configurações do Aplicativo ou via API do Didit no endpoint GET /v3/webhook/.

2. Configuração do Servidor Fastify

Crie um arquivo app.js. O Fastify precisa do corpo bruto para verificação de assinatura, então o configuraremos para não analisar JSON automaticamente para nossa rota de webhook.

require('dotenv').config();
const fastify = require('fastify')({ logger: true });
const crypto = require('crypto');
const { Client } = require('pg');

const DIDIT_WEBHOOK_SECRET = process.env.DIDIT_WEBHOOK_SECRET;
const DATABASE_URL = process.env.DATABASE_URL;

const pgClient = new Client({ connectionString: DATABASE_URL });

// Registra um parser de conteúdo para 'application/json' que deixa o corpo bruto para rotas específicas
fastify.addContentTypeParser('application/json', { parseAs: 'buffer' }, function (req, body, done) {
  if (req.raw.url === '/webhooks/didit') {
    done(null, body); // Deixa bruto para o endpoint do webhook
  } else {
    try {
      const json = JSON.parse(body.toString());
      done(null, json);
    } catch (error) {
      error.statusCode = 400;
      done(error, undefined);
    }
  }
});

fastify.post('/webhooks/didit', async (request, reply) => {
  const signature = request.headers['x-signature'];
  const timestamp = request.headers['x-timestamp'];
  const rawBody = request.body;

  if (!signature || !timestamp || !rawBody) {
    reply.code(400).send({ message: 'Assinatura, timestamp ou corpo ausentes' });
    return;
  }

  // 1. Verificar assinatura HMAC-SHA256
  const expectedSignature = crypto
    .createHmac('sha256', DIDIT_WEBHOOK_SECRET)
    .update(`${timestamp}.${rawBody.toString()}`)
    .digest('hex');

  if (expectedSignature !== signature) {
    reply.code(403).send({ message: 'Assinatura inválida' });
    return;
  }

  // 2. Validar timestamp (ex: dentro de 5 minutos para prevenir ataques de replay)
  const fiveMinutesAgo = Date.now() - (5 * 60 * 1000);
  if (parseInt(timestamp) < fiveMinutesAgo) {
    reply.code(403).send({ message: 'Timestamp muito antigo' });
    return;
  }

  // 3. Analisar corpo JSON após a verificação
  let payload;
  try {
    payload = JSON.parse(rawBody.toString());
  } catch (error) {
    reply.code(400).send({ message: 'Payload JSON inválido' });
    return;
  }

  fastify.log.info('Webhook Didit recebido:', payload);

  // 4. Processar o payload do webhook (ex: armazenar no DB, atualizar status do usuário)
  try {
    await pgClient.query(
      'INSERT INTO webhooks (event_id, event_type, payload, received_at) VALUES ($1, $2, $3, NOW())',
      [payload.id, payload.event, JSON.stringify(payload)]
    );
    // Exemplo: Atualizar status do usuário com base em payload.status
    // await pgClient.query(
    //   'UPDATE users SET verification_status = $1 WHERE didit_session_id = $2',
    //   [payload.status, payload.session_id]
    // );
    reply.code(200).send({ message: 'Webhook recebido e processado' });
  } catch (dbError) {
    fastify.log.error('Erro de banco de dados:', dbError);
    reply.code(500).send({ message: 'Erro interno do servidor' });
  }
});

const start = async () => {
  try {
    await pgClient.connect();
    fastify.log.info('Conectado ao PostgreSQL');
    await fastify.listen({ port: 3000, host: '0.0.0.0' });
  } catch (err) {
    fastify.log.error(err);
    process.exit(1);
  }
};

start();

Armazenando Dados de Webhook no PostgreSQL

Persistir dados de webhook é crucial para auditoria, depuração e garantia da integridade dos dados. O PostgreSQL é um banco de dados relacional robusto, ideal para essa tarefa.

1. Esquema do Banco de Dados

Primeiro, crie uma tabela para armazenar seus eventos de webhook. Este esquema oferece um bom ponto de partida:

CREATE TABLE webhooks (
    id SERIAL PRIMARY KEY,
    event_id VARCHAR(255) UNIQUE NOT NULL, -- ID de evento exclusivo do Didit
    event_type VARCHAR(255) NOT NULL,
    payload JSONB NOT NULL, -- Armazena o payload JSON completo
    received_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);

2. Integrando com Fastify

Como mostrado no exemplo app.js, integramos o cliente pg para conectar ao seu banco de dados PostgreSQL e inserir o payload do webhook recebido. A coluna payload JSONB NOT NULL é perfeita para armazenar o objeto JSON completo, permitindo consultas flexíveis posteriormente sem alterações de esquema predefinidas para cada novo campo que o Didit possa introduzir.

Lembre-se de tratar erros potenciais do banco de dados de forma graciosa. O exemplo acima inclui um bloco básico try-catch para operações de banco de dados.

Protegendo Seu Endpoint de Webhook

A segurança é primordial ao lidar com dados sensíveis de verificação de identidade. O Didit emprega assinaturas HMAC-SHA256 para garantir que os webhooks recebidos sejam legítimos e não adulterados.

1. Verificação de Assinatura HMAC

Cada solicitação de webhook do Didit inclui dois cabeçalhos cruciais: X-Signature e X-Timestamp. O cabeçalho X-Signature contém uma assinatura HMAC-SHA256 gerada usando sua chave secreta de webhook exclusiva e o corpo bruto da solicitação concatenado com o timestamp. Seu listener deve:

1. Recuperar seu DIDIT_WEBHOOK_SECRET.
2. Extrair os cabeçalhos X-Signature e X-Timestamp.
3. Reconstruir o payload assinado: `${timestamp}.${rawBody}`.
4. Gerar sua própria assinatura HMAC-SHA256 usando sua chave secreta e o payload reconstruído.
5. Comparar sua assinatura gerada com o X-Signature da solicitação. Se não coincidirem, rejeite a solicitação.

O exemplo Fastify fornecido demonstra este processo exato, garantindo que apenas webhooks autênticos do Didit sejam processados.

2. Validação de Timestamp

O cabeçalho X-Timestamp é vital para prevenir ataques de replay. Um ataque de replay ocorre quando um invasor intercepta um webhook legítimo e o reenvia mais tarde. Ao verificar se o timestamp é recente (por exemplo, dentro de 5 minutos da hora atual), você pode mitigar esse risco. O trecho de código Fastify inclui uma verificação para garantir que o timestamp não seja muito antigo.

Como o Didit Ajuda

A plataforma do Didit foi projetada para tornar a integração da verificação de identidade contínua e segura. Nossa arquitetura modular permite que você "plug-and-play" várias verificações de identidade, desde Verificação de ID para análise robusta de documentos até Verificação NFC para verificações de alta segurança de passaportes/documentos de identidade eletrônicos, e Triagem e Monitoramento AML para conformidade. O sistema de webhook é um componente central dessa modularidade, fornecendo atualizações em tempo real que permitem orquestrar fluxos de trabalho KYC complexos sem polling constante.

A abordagem nativa de IA do Didit significa que nossos sistemas estão constantemente aprendendo e se adaptando, fornecendo precisão superior e detecção de fraudes. A documentação clara da API e a mentalidade "developer-first", combinadas com recursos como KYC Core Gratuito e sem taxas de configuração, facilitam o início. Nossos webhooks fornecem dados de identidade estruturados, permitindo que sua aplicação reaja de forma inteligente aos resultados da verificação e automatize a confiança em escala, globalmente. Seja para verificar a idade usando a Estimativa de Idade do Didit ou garantir que um usuário seja uma pessoa real com Prova de Vida Passiva e Ativa, o Didit fornece as ferramentas e o feedback em tempo real necessários para uma solução de identidade robusta.

Pronto para Começar?

Quer ver o Didit em ação? Obtenha uma demonstração gratuita hoje.

Comece a verificar identidades gratuitamente com o nível gratuito do Didit.