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

Integração Segura de WebhooksA implementação da verificação de assinatura HMAC-SHA256 é crucial para garantir a autenticidade e integridade dos payloads de webhook da Didit, protegendo a sua aplicação contra pedidos forjados e mantendo a segurança dos dados.

Processamento de Dados em Tempo RealUtilize webhooks para receber notificações instantâneas sobre mudanças de estado da sessão de verificação de identidade, permitindo que a sua aplicação reaja imediatamente e automatize fluxos de trabalho de onboarding de utilizadores ou gestão de riscos.

Armazenamento de Dados EscalávelAproveite o PostgreSQL para armazenar e gerir eficientemente os dados de webhook, permitindo consultas robustas, auditorias e integração com os seus sistemas de gestão de utilizadores existentes, garantindo a persistência e fiabilidade dos dados.

A Vantagem Modular da DiditA plataforma de identidade modular da Didit e o sistema abrangente de webhook simplificam a integração, fornecendo aos programadores 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.

Compreender os Webhooks da Didit e a Sua Importância

No mundo da verificação de identidade, o feedback em tempo real é primordial. Quer esteja a integrar novos utilizadores, a prevenir fraudes ou a garantir a conformidade, saber o estado de uma sessão de verificação à medida que acontece é crítico. É aqui que entram os webhooks. Os webhooks da Didit fornecem uma forma automatizada de receber notificações sobre eventos que ocorrem nos seus fluxos de trabalho de verificação de identidade, como a conclusão, falha ou necessidade de ações adicionais de uma sessão.

Em vez de consultar constantemente a API da Didit para atualizações, o que pode ser ineficiente e levar a atrasos, os webhooks enviam dados diretamente para o seu endpoint configurado. Esta arquitetura orientada por eventos garante que a sua aplicação tem sempre as informações mais atualizadas, permitindo um processamento imediato e uma experiência de utilizador mais fluida. Por exemplo, assim que um utilizador conclui com sucesso as verificações de Verificação de ID e Vivacidade Passiva e Ativa da Didit, um webhook pode acionar o próximo passo no seu fluxo de integração instantaneamente.

A Didit oferece versões de webhook configuráveis, sendo a v3 o padrão recomendado pela sua estrutura de payload abrangente. Pode definir o seu URL de webhook, versão e até políticas de retenção de dados diretamente através da Consola de Negócios da Didit ou via API, dando-lhe controlo total sobre o seu fluxo de dados e obrigações de conformidade.

Configurar o Seu Ouvinte de Webhook Fastify

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

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

Primeiro, inicialize o 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 ficheiro .env para armazenar a sua chave secreta de webhook da Didit e os detalhes de conexão do PostgreSQL:

DIDIT_WEBHOOK_SECRET=sua_chave_secreta_webhook_didit
DATABASE_URL=postgresql://utilizador:palavra-passe@servidor:porta/base_de_dados

Pode obter a sua DIDIT_WEBHOOK_SECRET na Consola de Negócios da Didit em Definições da Aplicação ou através do endpoint GET /v3/webhook/ da API da Didit.

2. Configuração do Servidor Fastify

Crie um ficheiro app.js. O Fastify precisa do corpo bruto para a verificação da assinatura, por isso vamos configurá-lo para não analisar JSON automaticamente para a 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 });

// Regista 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, carimbo de data/hora ou corpo em falta' });
    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 carimbo de data/hora (ex: dentro de 5 minutos para prevenir ataques de repetição)
  const fiveMinutesAgo = Date.now() - (5 * 60 * 1000);
  if (parseInt(timestamp) < fiveMinutesAgo) {
    reply.code(403).send({ message: 'Carimbo de data/hora muito antigo' });
    return;
  }

  // 3. Analisar corpo JSON após 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 na BD, atualizar estado do utilizador)
  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 estado do utilizador com base em payload.status
    // await pgClient.query(
    //   'UPDATE utilizadores 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 na base 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();

Armazenar Dados de Webhook em PostgreSQL

Persistir dados de webhook é crucial para auditoria, depuração e garantia da integridade dos dados. O PostgreSQL é uma base de dados relacional robusta ideal para esta tarefa.

1. Esquema da Base de Dados

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

CREATE TABLE webhooks (
    id SERIAL PRIMARY KEY,
    event_id VARCHAR(255) UNIQUE NOT NULL, -- ID de evento único da 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. Integração com Fastify

Conforme mostrado no exemplo app.js, integramos o cliente pg para conectar à sua base de dados PostgreSQL e inserir o payload do webhook recebido. A coluna payload JSONB NOT NULL é perfeita para armazenar o objeto JSON inteiro, permitindo consultas flexíveis posteriormente sem mudanças de esquema predefinidas para cada novo campo que a Didit possa introduzir.

Lembre-se de lidar com potenciais erros da base de dados de forma graciosa. O exemplo acima inclui um bloco try-catch básico para operações da base de dados.

Proteger o Seu Endpoint de Webhook

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

1. Verificação de Assinatura HMAC

Cada solicitação de webhook da Didit inclui dois cabeçalhos cruciais: X-Signature e X-Timestamp. O cabeçalho X-Signature contém uma assinatura HMAC-SHA256 gerada usando a sua chave secreta de webhook exclusiva e o corpo da solicitação bruto concatenado com o carimbo de data/hora. O seu ouvinte deve:

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

O exemplo Fastify fornecido demonstra este processo exato, garantindo que apenas webhooks autênticos da Didit são processados.

2. Validação do Carimbo de Data/Hora

O cabeçalho X-Timestamp é vital para prevenir ataques de repetição. Um ataque de repetição ocorre quando um atacante interceta um webhook legítimo e o reenvia mais tarde. Ao verificar se o carimbo de data/hora é recente (por exemplo, dentro de 5 minutos da hora atual), pode mitigar este risco. O snippet de código Fastify inclui uma verificação para garantir que o carimbo de data/hora não é muito antigo.

Como a Didit Ajuda

A plataforma da Didit foi desenhada para tornar a integração da verificação de identidade contínua e segura. A nossa arquitetura modular permite-lhe "plug-and-play" várias verificações de identidade, desde a Verificação de ID para análise robusta de documentos, à Verificação NFC para verificações de alta segurança de ePassport/eID, e Rastreio e Monitorização AML para conformidade. O sistema de webhook é um componente central desta modularidade, fornecendo atualizações em tempo real que lhe permitem orquestrar fluxos de trabalho KYC complexos sem polling constante.

A abordagem nativa de IA da Didit significa que os nossos sistemas estão constantemente a aprender e a adaptar-se, proporcionando uma precisão superior e deteção de fraude. A documentação clara da API e a mentalidade "developer-first", combinadas com funcionalidades como o KYC Core Gratuito e sem taxas de configuração, facilitam o início. Os nossos webhooks fornecem dados de identidade estruturados, permitindo que a sua aplicação reaja inteligentemente aos resultados da verificação e automatize a confiança em escala, globalmente. Quer precise de verificar a idade usando a Estimativa de Idade da Didit ou garantir que um utilizador é uma pessoa real com Vivacidade Passiva e Ativa, a Didit fornece as ferramentas e o feedback em tempo real necessários para uma solução de identidade robusta.

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.