Proteja seu Backend Node.js: Validação HMAC para Webhooks Didit (PT-BR)

Proteja a Integridade dos Dados A validação de assinatura HMAC é essencial para verificar a autenticidade e integridade dos payloads de webhook, protegendo seu backend contra solicitações adulteradas ou fraudulentas.

Previna Ataques de Replay A validação de timestamp, em conjunto com as assinaturas HMAC, adiciona uma camada crucial de defesa contra ataques de replay, garantindo que apenas notificações recentes sejam processadas.

Integração Sem Complicações A abordagem da Didit, que prioriza o desenvolvedor, oferece documentação e ferramentas claras, tornando a integração do processamento seguro de webhooks em sua aplicação Node.js direta e eficiente.

Infraestrutura Segura da Didit A plataforma da Didit foi construída pensando na segurança, oferecendo notificações KYC em tempo real via webhooks com robusta verificação de assinatura HMAC, permitindo que você construa soluções de identidade confiáveis e compatíveis.

A Necessidade Crítica de Segurança em Webhooks

Webhooks são ferramentas poderosas para comunicação em tempo real entre serviços, permitindo atualizações instantâneas e arquiteturas orientadas a eventos. No contexto da verificação de identidade, a Didit usa webhooks para notificar seu backend sobre a conclusão de sessões de verificação, resultados de triagem AML ou outros eventos críticos relacionados à identidade. Embora incrivelmente eficientes, os webhooks também introduzem desafios de segurança. Sem a validação adequada, um ator mal-intencionado poderia enviar payloads de webhook forjados ou alterados, levando a processamento incorreto de dados, ações não autorizadas ou até mesmo comprometimento do sistema.

É aqui que a validação de assinatura HMAC (Hash-based Message Authentication Code) se torna indispensável. HMAC fornece um mecanismo criptográfico para verificar a autenticidade e a integridade de uma mensagem. Ao usar uma chave secreta compartilhada, seu backend pode garantir que o payload do webhook se originou da Didit e não foi adulterado em trânsito. Para qualquer sistema que lida com dados de identidade sensíveis, como os processados pelos serviços de Verificação de ID, Triagem AML ou Prova de Endereço da Didit, esse nível de segurança não é apenas uma boa prática — é uma necessidade.

Entendendo a Validação de Assinatura HMAC

A validação HMAC funciona gerando uma assinatura única para cada payload de webhook usando uma chave secreta conhecida apenas pela Didit e sua aplicação. Quando seu backend Node.js recebe um webhook, ele executa o mesmo cálculo de assinatura usando sua cópia da chave secreta. Se a assinatura calculada corresponder à assinatura fornecida nos cabeçalhos do webhook, você pode ter certeza de que o payload é autêntico e não foi adulterado.

Os webhooks da Didit incluem um cabeçalho X-Signature contendo a assinatura HMAC-SHA256 e um cabeçalho X-Timestamp. O timestamp é crucial para prevenir ataques de replay. Um ataque de replay ocorre quando um invasor intercepta um webhook legítimo e o reenvia mais tarde. Ao validar que o timestamp é recente (por exemplo, dentro de uma janela de 5 minutos), você pode descartar solicitações antigas e potencialmente reproduzidas.

Implementando a Validação HMAC em Node.js

Vamos detalhar as etapas para implementar a validação de assinatura HMAC para webhooks da Didit em uma aplicação Node.js Express. Você precisará ter acesso à sua chave secreta do webhook, que pode ser encontrada em seu Didit Business Console ou recuperada via API de gerenciamento.

1. Configure Seu Endpoint de Webhook

Primeiro, configure um endpoint Express que possa receber requisições POST. É crucial acessar o corpo bruto da requisição antes de qualquer middleware de parseamento JSON, pois a assinatura é calculada sobre o payload bruto.

const express = require('express');
const crypto = require('crypto');
const bodyParser = require('body-parser');

const app = express();
const DIDIT_WEBHOOK_SECRET = process.env.DIDIT_WEBHOOK_SECRET; // Armazene com segurança!

// Middleware para obter o corpo bruto
app.use(bodyParser.json({ verify: (req, res, buf) => {
  req.rawBody = buf.toString();
}}));

app.post('/api/webhooks/didit', (req, res) => {
  // A lógica de processamento do webhook virá aqui
  res.status(200).send('Webhook recebido');
});

app.listen(3000, () => console.log('Servidor rodando na porta 3000'));

2. Verifique a Assinatura HMAC

Dentro do seu manipulador de webhook, você extrairá o timestamp e a assinatura dos cabeçalhos, reconstruirá o payload assinado e comparará sua assinatura calculada com a fornecida pela Didit.

app.post('/api/webhooks/didit', (req, res) => {
  const signatureHeader = req.headers['x-signature'];
  const timestampHeader = req.headers['x-timestamp'];
  const rawBody = req.rawBody;

  if (!signatureHeader || !timestampHeader || !rawBody) {
    return res.status(400).send('Cabeçalhos ou corpo do webhook ausentes.');
  }

  const [algorithm, diditSignature] = signatureHeader.split('=');

  if (algorithm !== 'sha256') {
    return res.status(400).send('Algoritmo de assinatura não suportado.');
  }

  // Reconstrua a string do payload assinado
  const signedPayload = `${timestampHeader}.${rawBody}`;

  // Calcule sua própria assinatura
  const expectedSignature = crypto
    .createHmac('sha256', DIDIT_WEBHOOK_SECRET)
    .update(signedPayload)
    .digest('hex');

  // Compare as assinaturas de forma segura
  const signatureMatches = crypto.timingSafeEqual(
    Buffer.from(diditSignature, 'utf8'),
    Buffer.from(expectedSignature, 'utf8')
  );

  if (!signatureMatches) {
    console.warn('Incompatibilidade de assinatura do webhook!');
    return res.status(401).send('Assinatura inválida.');
  }

  // A assinatura é válida, agora verifique o timestamp
  // ... (validação de timestamp na próxima etapa)

  // Processe o evento
  console.log('Webhook validado com sucesso:', req.body);
  res.status(200).send('Webhook recebido e processado.');
});

3. Valide o Timestamp

Após verificar a assinatura, certifique-se de que o webhook não é um replay. Uma prática comum é permitir uma pequena janela de tolerância (por exemplo, 5 minutos) para atrasos de rede.

// ... (dentro do manipulador de webhook, após a validação da assinatura)

  const fiveMinutesAgo = Date.now() / 1000 - (5 * 60); // 5 minutos em segundos
  const eventTimestamp = parseInt(timestampHeader, 10);

  if (isNaN(eventTimestamp) || eventTimestamp < fiveMinutesAgo) {
    console.warn('Timestamp do webhook muito antigo ou inválido!');
    return res.status(401).send('Timestamp inválido ou antigo.');
  }

  // Agora você pode analisar e processar com segurança o corpo JSON
  try {
    const event = JSON.parse(rawBody);
    console.log('Evento Didit processado:', event);
    // Exemplo: Atualize o status do usuário com base em event.database_validation.status

    // Estrutura do Relatório de Validação de Banco de Dados da Didit:
    // const validationStatus = event.database_validation.status;
    // const matchType = event.database_validation.match_type;
    // console.log(`Status da Validação: ${validationStatus}, Tipo de Correspondência: ${matchType}`);

    res.status(200).send('Webhook recebido e processado.');
  } catch (error) {
    console.error('Erro ao analisar o corpo do webhook:', error);
    res.status(400).send('Corpo JSON inválido.');
  }
});

Melhores Práticas para o Tratamento de Webhooks

• Armazene Segredos com Segurança: Nunca coloque sua chave secreta de webhook diretamente no código. Use variáveis de ambiente ou um serviço seguro de gerenciamento de segredos.
• Idempotência: Projete seus manipuladores de webhook para serem idempotentes. Isso significa que processar o mesmo webhook várias vezes (devido a retries, por exemplo) deve ter o mesmo efeito que processá-lo uma vez.
• Processamento Assíncrono: Para tarefas de longa duração, confirme o webhook imediatamente com uma resposta 200 OK e, em seguida, processe o payload assincronamente usando uma fila de mensagens. Isso evita timeouts e garante que a Didit não continue tentando reenviar o webhook.
• Registro e Monitoramento: Implemente um registro robusto para todos os webhooks recebidos, incluindo falhas de validação. Monitore seu endpoint de webhook para atividades incomuns ou altas taxas de erro.
• Tratamento de Erros: Retorne códigos de status HTTP apropriados (por exemplo, 400 para requisição inválida, 401 para não autorizado, 500 para erros do servidor) para ajudar a Didit a entender se uma nova tentativa é necessária.

Como a Didit Ajuda

A Didit é projetada para ser uma plataforma de identidade nativa de IA e que prioriza o desenvolvedor, tornando integrações seguras como o processamento de webhooks simples e confiáveis. Nossa arquitetura modular significa que você pode facilmente integrar verificações de identidade, incluindo Verificação de ID, Liveness Passivo e Ativo, e Triagem e Monitoramento AML, e receber atualizações em tempo real via webhooks seguros. A Didit fornece documentação e exemplos claros para a integração de webhooks, garantindo que você possa configurar rapidamente canais de comunicação robustos e seguros.

Acreditamos em tornar a verificação de identidade acessível e poderosa. É por isso que oferecemos KYC Core Gratuito, um modelo de pagamento por verificação bem-sucedida e absolutamente nenhuma taxa de configuração. Ao alavancar a plataforma da Didit, você obtém acesso a uma solução global e escalável que automatiza a confiança e orquestra o risco, tudo isso mantendo os mais altos padrões de segurança, incluindo a validação de assinatura HMAC para notificações em tempo real.

Pronto para Começar?

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

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