Integração Didit: Proteger Webhooks com Cloudflare Workers (PT-PT)

Segurança Reforçada com Cloudflare WorkersOs Cloudflare Workers oferecem um ambiente serverless ideal para processar webhooks de forma segura, proporcionando proteção na "edge" e verificação eficiente de assinaturas.

A Verificação de Assinatura HMAC é CrucialVerifique sempre a assinatura HMAC-SHA256 dos webhooks recebidos para garantir a sua autenticidade e integridade, prevenindo a injeção ou adulteração de dados não autorizados.

A Validação de Timestamp Atenua Ataques de ReplayImplemente verificações de timestamp para garantir que os pedidos de webhook são recentes, protegendo contra ataques de "replay" onde pedidos antigos e legítimos são reenviados por agentes maliciosos.

Didit Simplifica a Verificação Segura de IdentidadeA plataforma nativa de IA da Didit fornece notificações de webhook robustas e em tempo real para todos os produtos de verificação de identidade, garantindo a entrega segura e fiável de dados para as suas aplicações.

No cenário digital interconectado de hoje, os webhooks são a pedra angular da comunicação em tempo real entre serviços. Permitem notificações instantâneas para eventos como resultados de verificação de identidade, confirmações de pagamento e atividade do utilizador. No entanto, a conveniência dos webhooks vem com um desafio de segurança crítico: garantir a autenticidade e integridade dos dados recebidos. Sem as salvaguardas adequadas, a sua aplicação pode ser vulnerável a "spoofing", adulteração ou ataques de "replay".

Este guia irá acompanhá-lo na construção de um endpoint de webhook seguro para a verificação de identidade Didit usando Cloudflare Workers. Os Cloudflare Workers oferecem uma plataforma poderosa e "serverless" na "edge", ideal para processar e proteger webhooks com latência mínima e máxima fiabilidade. A Didit, como plataforma de identidade nativa de IA, baseia-se em webhooks seguros para fornecer notificações KYC em tempo real, tornando esta integração crucial para qualquer negócio que utilize as robustas soluções de verificação de identidade da Didit.

Porquê Proteger os Seus Webhooks?

Imagine receber uma notificação de webhook que afirma falsamente que um utilizador passou na Verificação de ID, quando na realidade, falhou. Ou talvez um agente malicioso reproduza um webhook antigo e legítimo para desencadear uma ação no seu sistema várias vezes. Estes cenários destacam a necessidade crítica de segurança dos webhooks.

As principais ameaças aos endpoints de webhook incluem:

• Spoofing: Um atacante envia um webhook falso, fingindo ser a Didit, para enganar o seu sistema a tomar ações não autorizadas.
• Adulteração: Um atacante interceta um webhook legítimo e modifica a sua "payload" antes que este chegue ao seu servidor.
• Ataques de Replay: Um atacante captura um webhook legítimo e reenvia-o mais tarde para desencadear a mesma ação novamente, o que pode levar a transações duplicadas ou outros problemas.

Proteger os seus webhooks envolve verificar a identidade do remetente e garantir que os dados não foram alterados. A Didit fornece um mecanismo robusto para isso através de assinaturas HMAC-SHA256 e validação de timestamp, que implementaremos no nosso Cloudflare Worker.

Configurar o Seu Segredo de Webhook Didit

Antes de poder verificar os webhooks Didit, precisa da sua Chave Secreta de Webhook única. Esta chave é fundamental para a verificação da assinatura criptográfica. Veja como obtê-la:

1. Inicie sessão na sua Consola Didit.
2. Navegue até Definições → Chaves API.
3. Copie a sua Chave Secreta de Webhook.

Esta chave secreta deve ser armazenada de forma segura e nunca exposta publicamente. Para Cloudflare Workers, é melhor armazená-la como um "Worker secret" ou uma variável de ambiente.

Construir um Cloudflare Worker Seguro para Webhooks Didit

Os Cloudflare Workers são aplicações JavaScript, TypeScript ou WebAssembly que são executadas na rede global da Cloudflare, perto dos seus utilizadores. Isso torna-os incrivelmente rápidos e escaláveis para lidar com pedidos de webhook recebidos. Aqui está um guia passo a passo para criar um Worker que processa com segurança os webhooks Didit.

1. Crie o Seu Cloudflare Worker

Primeiro, configure um novo projeto Cloudflare Worker. Pode fazê-lo usando a ferramenta CLI wrangler:

npx wrangler generate didit-webhook-handler
cd didit-webhook-handler

2. Adicione o Seu Segredo de Webhook Didit como um Segredo Cloudflare

Para manter o seu segredo de webhook seguro, adicione-o como um segredo ao seu Worker:

npx wrangler secret put DIDIT_WEBHOOK_SECRET

Quando solicitado, cole a sua Chave Secreta de Webhook da Consola Didit.

3. Implemente a Lógica do Webhook em index.js

O ficheiro index.js do seu Worker conterá a lógica para receber, validar e processar os webhooks Didit. Os passos principais são:

1. Ler o Corpo do Pedido Bruto: A assinatura HMAC é gerada a partir do corpo do pedido bruto, por isso é crucial não o analisar antes da verificação.
2. Verificar a Assinatura HMAC-SHA256: Compare a assinatura fornecida no cabeçalho X-Signature com uma assinatura que gera usando o seu DIDIT_WEBHOOK_SECRET e o corpo do pedido bruto.
3. Validar o Timestamp: Verifique o cabeçalho X-Timestamp para garantir que o pedido é recente (por exemplo, dentro de 5 minutos) para evitar ataques de "replay".
4. Analisar JSON e Processar: Se a verificação for bem-sucedida, analise o corpo JSON e lide com o resultado da verificação de identidade.

Aqui está um exemplo básico do código do Worker:

import { createHmac } from 'crypto'; // Cloudflare Workers provide 'crypto' module

export default {
  async fetch(request, env, ctx) {
    if (request.method !== 'POST') {
      return new Response('Method Not Allowed', { status: 405 });
    }

    const diditWebhookSecret = env.DIDIT_WEBHOOK_SECRET;
    if (!diditWebhookSecret) {
      return new Response('Webhook secret not configured', { status: 500 });
    }

    const signature = request.headers.get('X-Signature');
    const timestamp = request.headers.get('X-Timestamp');
    const rawBody = await request.text();

    if (!signature || !timestamp || !rawBody) {
      return new Response('Missing required webhook headers or body', { status: 400 });
    }

    // 1. Validate Timestamp (e.g., within 5 minutes)
    const FIVE_MINUTES_IN_SECONDS = 300;
    const currentTimestamp = Math.floor(Date.now() / 1000);
    if (Math.abs(currentTimestamp - parseInt(timestamp, 10)) > FIVE_MINUTES_IN_SECONDS) {
      return new Response('Webhook timestamp too old or in the future', { status: 403 });
    }

    // 2. Verify HMAC-SHA256 Signature
    const expectedSignature = createHmac('sha256', diditWebhookSecret)
      .update(`${timestamp}.${rawBody}`)
      .digest('hex');

    if (expectedSignature !== signature) {
      return new Response('Invalid webhook signature', { status: 403 });
    }

    // 3. Process the webhook payload
    try {
      const payload = JSON.parse(rawBody);
      // Log or process the payload, e.g., update user status in your database
      console.log('Received Didit webhook:', payload);

      // Example: Accessing verification status
      if (payload.event === 'session.completed' && payload.data.status === 'approved') {
        console.log(`User ${payload.data.vendor_data} successfully verified.`);
        // Trigger further actions like granting access or updating user profile
      }
      // Didit offers various products like ID Verification, Passive & Active Liveness, and AML Screening.
      // The webhook payload will reflect results from these checks.

      return new Response('Webhook processed successfully', { status: 200 });
    } catch (error) {
      console.error('Error parsing webhook body:', error);
      return new Response('Error parsing JSON payload', { status: 400 });
    }
  },
};

4. Implemente o Seu Worker

Assim que o seu código estiver pronto, implemente-o na Cloudflare:

npx wrangler deploy

Após a implementação, a Cloudflare fornecerá um URL para o seu Worker. Este é o endpoint que irá configurar na sua Consola Didit para receber webhooks.

Configurar a Didit para Enviar Webhooks

Com o seu Cloudflare Worker seguro implementado, o passo final é indicar à Didit onde enviar as suas notificações em tempo real:

1. Volte à sua Consola Didit.
2. Navegue até Fluxos de Trabalho e selecione o fluxo de trabalho que deseja configurar (por exemplo, o seu fluxo de trabalho KYC que usa Verificação de ID da Didit e "Passive & Active Liveness").
3. Nas definições do fluxo de trabalho, encontre a configuração do URL do Webhook.
4. Introduza o URL do seu Cloudflare Worker implementado.
5. Guarde as suas alterações.

Agora, sempre que uma sessão de verificação de identidade for concluída ou o seu estado for alterado, a Didit enviará uma notificação de webhook segura para o seu Cloudflare Worker, que então a validará e processará.

Como a Didit Ajuda

A Didit foi concebida com a segurança e a experiência do programador no centro. A nossa plataforma de identidade nativa de IA fornece uma arquitetura modular que permite compor fluxos de trabalho de verificação complexos com facilidade. No que diz respeito aos webhooks, a Didit simplifica o processo ao:

• Fornecer Notificações de Webhook Seguras: Todos os webhooks Didit são assinados com uma assinatura HMAC-SHA256 e incluem um timestamp, garantindo a autenticidade e integridade dos dados que recebe. Isto é crucial para produtos como Verificação de ID, "1:1 Face Match" e "AML Screening", onde a precisão dos dados é fundamental.
• Atualizações em Tempo Real: Obtenha notificações instantâneas para cada fase do processo de verificação, permitindo que a sua aplicação reaja imediatamente aos resultados da verificação do utilizador.
• Dados Abrangentes: As "payloads" dos webhooks incluem todos os detalhes necessários sobre a sessão de verificação, incluindo os resultados de vários produtos Didit, como "Passive & Active Liveness", Verificação de Telefone e E-mail, e Comprovativo de Morada.
• Abordagem "Developer-First": A Didit oferece um "sandbox" instantâneo, documentação pública clara e APIs limpas, tornando a integração simples. O nosso nível gratuito de KYC Core e o modelo "pay-per-successful-check", sem taxas de configuração, facilitam o início e a escalabilidade.

Ao integrar os webhooks Didit com um Cloudflare Worker seguro, estabelece um canal resiliente e fiável para atualizações de verificação de identidade em tempo real, protegendo o seu negócio e os seus utilizadores.

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.