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

Proteja a Integridade dos DadosA validação da assinatura HMAC é essencial para verificar a autenticidade e a integridade das cargas de dados dos webhooks, protegendo o seu backend contra pedidos adulterados ou fraudulentos.

Previna Ataques de ReplayA validação de registo de data e hora, em conjunto com as assinaturas HMAC, adiciona uma camada crucial de defesa contra ataques de replay, garantindo que apenas notificações recentes são processadas.

Integração Sem ComplicaçõesA abordagem da Didit focada no programador oferece documentação e ferramentas claras, tornando a integração do processamento seguro de webhooks na sua aplicação Node.js direta e eficiente.

Infraestrutura Segura da DiditA plataforma da Didit é construída com a segurança em mente, oferecendo notificações KYC em tempo real via webhooks com verificação robusta de assinatura HMAC, permitindo-lhe construir soluções de identidade fiáveis e compatíveis.

A Necessidade Crítica da Segurança de 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 utiliza webhooks para notificar o seu backend sobre a conclusão de sessões de verificação, resultados de triagem AML, ou outros eventos críticos relacionados com a identidade. Embora incrivelmente eficientes, os webhooks também introduzem desafios de segurança. Sem a validação adequada, um ator malicioso poderia enviar cargas de webhook forjadas ou alteradas, 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. O HMAC fornece um mecanismo criptográfico para verificar tanto a autenticidade quanto a integridade de uma mensagem. Ao usar uma chave secreta partilhada, o seu backend pode garantir que a carga do webhook se originou da Didit e não foi adulterada em trânsito. Para qualquer sistema que lide com dados de identidade sensíveis, como os processados pelos serviços de Verificação de ID, Triagem AML ou Prova de Morada da Didit, este nível de segurança não é apenas uma boa prática — é uma necessidade.

Compreender a Validação de Assinatura HMAC

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

Os webhooks da Didit incluem um cabeçalho X-Signature contendo a assinatura HMAC-SHA256 e um cabeçalho X-Timestamp. O registo de data e hora é crucial para prevenir ataques de replay. Um ataque de replay ocorre quando um atacante interceta um webhook legítimo e o reenvia mais tarde. Ao validar que o registo de data e hora é recente (por exemplo, dentro de uma janela de 5 minutos), pode descartar pedidos antigos, potencialmente repetidos.

Implementar a Validação HMAC em Node.js

Vamos percorrer os passos para implementar a validação de assinatura HMAC para webhooks Didit numa aplicação Node.js Express. Precisará de acesso à sua chave secreta de webhook, que pode ser encontrada na sua Consola de Negócios Didit ou recuperada através da API de gestão.

1. Configurar o Seu Ponto de Acesso de Webhook

Primeiro, configure um ponto de acesso Express que possa receber pedidos POST. É crucial aceder ao corpo do pedido bruto antes de qualquer middleware de análise JSON, pois a assinatura é calculada sobre a carga bruta.

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; // Armazenar de forma segura!

// 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 irá aqui
  res.status(200).send('Webhook recebido');
});

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

2. Verificar a Assinatura HMAC

Dentro do seu manipulador de webhook, irá extrair o registo de data e hora e a assinatura dos cabeçalhos, reconstruir a carga assinada e comparar a 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 em falta.');
  }

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

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

  // Reconstruir a string da carga assinada
  const signedPayload = `${timestampHeader}.${rawBody}`;

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

  // Comparar 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 verificar o registo de data e hora
  // ... (validação do registo de data e hora no próximo passo)

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

3. Validar o Registo de Data e Hora

Após verificar a assinatura, garanta 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 do 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('Registo de data e hora do webhook muito antigo ou inválido!');
    return res.status(401).send('Registo de data e hora inválido ou antigo.');
  }

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

    // Estrutura do Relatório de Validação de Base de Dados da Didit:
    // const validationStatus = event.database_validation.status;
    // const matchType = event.database_validation.match_type;
    // console.log(`Estado 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 Manuseamento de Webhooks

• Armazene Segredos de Forma Segura: Nunca codifique a sua chave secreta de webhook. Use variáveis de ambiente ou um serviço seguro de gestão de segredos.
• Idempotência: Desenvolva os seus manipuladores de webhook para serem idempotentes. Isto significa que processar o mesmo webhook várias vezes (devido a retentativas, por exemplo) deve ter o mesmo efeito que processá-lo uma vez.
• Processamento Assíncrono: Para tarefas demoradas, reconheça o webhook imediatamente com uma resposta 200 OK e, em seguida, processe a carga de forma assíncrona usando uma fila de mensagens. Isto previne tempos limite e garante que a Didit não continua a tentar novamente o webhook.
• Registo e Monitorização: Implemente um registo robusto para todos os webhooks recebidos, incluindo falhas de validação. Monitorize o seu ponto de acesso de webhook para atividades incomuns ou altas taxas de erro.
• Tratamento de Erros: Devolva códigos de estado HTTP apropriados (por exemplo, 400 para pedido inválido, 401 para não autorizado, 500 para erros de servidor) para ajudar a Didit a entender se é necessária uma nova tentativa.

Como a Didit Ajuda

A Didit foi projetada para ser uma plataforma de identidade nativa de IA e orientada para o programador, tornando integrações seguras como o processamento de webhooks diretas e fiáveis. A nossa arquitetura modular significa que pode facilmente ligar verificações de identidade, incluindo Verificação de ID, Liveness Passiva e Ativa, e Triagem e Monitorização AML, e receber atualizações em tempo real via webhooks seguros. A Didit fornece documentação e exemplos claros para integrar webhooks, garantindo que pode 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 sem taxas de configuração. Ao aproveitar a plataforma da Didit, obtém acesso a uma solução global e escalável que automatiza a confiança e orquestra o risco, tudo isto 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.