Protegendo Webhooks com Cloudflare Workers: Um Guia de Integração Didit (PT-BR)

Segurança Aprimorada com Cloudflare WorkersCloudflare Workers fornecem um ambiente serverless ideal para processar webhooks de forma segura, oferecendo proteção de ponta e verificação eficiente de assinatura.

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

Validação de Timestamp Mitiga Ataques de ReplayImplemente verificações de timestamp para garantir que as requisições de webhook sejam recentes, protegendo contra ataques de replay onde requisições antigas e legítimas são reenviadas por atores 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 entrega de dados segura e confiável para 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. Eles permitem notificações instantâneas para eventos como resultados de verificação de identidade, confirmações de pagamento e atividade do usuário. No entanto, a conveniência dos webhooks vem com um desafio de segurança crítico: garantir a autenticidade e a integridade dos dados recebidos. Sem as salvaguardas adequadas, sua aplicação pode estar vulnerável a falsificações, adulterações ou ataques de replay.

Este guia o guiará pela construção de um endpoint de webhook seguro para verificação de identidade Didit usando Cloudflare Workers. Cloudflare Workers oferecem uma plataforma poderosa e serverless na borda, ideal para processar e proteger webhooks com latência mínima e máxima confiabilidade. Didit, como uma plataforma de identidade nativa de IA, depende de webhooks seguros para entregar 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.

Por que Proteger Seus Webhooks?

Imagine receber uma notificação de webhook que afirma falsamente que um usuário passou na Verificação de ID, quando na realidade, ele falhou. Ou talvez um ator malicioso reproduza um webhook antigo e legítimo para acionar uma ação em seu sistema várias vezes. Esses cenários destacam a necessidade crítica de segurança de webhook.

As principais ameaças aos endpoints de webhook incluem:

• Spoofing (Falsificação): Um invasor envia um webhook falso, fingindo ser Didit, para enganar seu sistema e fazer com que ele execute ações não autorizadas.
• Tampering (Adulteração): Um invasor intercepta um webhook legítimo e modifica seu payload antes que ele chegue ao seu servidor.
• Replay Attacks (Ataques de Replay): Um invasor captura um webhook legítimo e o reenviará mais tarde para acionar a mesma ação novamente, potencialmente levando a transações duplicadas ou outros problemas.

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

Configurando Sua Chave Secreta de Webhook Didit

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

1. Faça login em seu Console Didit.
2. Navegue até Configurações → Chaves de API.
3. Copie sua Chave Secreta de Webhook.

Esta chave secreta deve ser armazenada com segurança e nunca exposta publicamente. Para Cloudflare Workers, é melhor armazená-la como um segredo do Worker ou uma variável de ambiente.

Construindo um Cloudflare Worker Seguro para Webhooks Didit

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

1. Crie Seu Cloudflare Worker

Primeiro, configure um novo projeto Cloudflare Worker. Você pode fazer isso usando a ferramenta CLI wrangler:

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

2. Adicione Sua Chave Secreta de Webhook Didit como um Segredo Cloudflare

Para manter sua chave secreta de webhook segura, adicione-a como um segredo ao seu Worker:

npx wrangler secret put DIDIT_WEBHOOK_SECRET

Quando solicitado, cole sua Chave Secreta de Webhook do Console Didit.

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

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

1. Leia o Corpo da Requisição Bruto: A assinatura HMAC é gerada a partir do corpo da requisição bruto, portanto, é crucial não analisá-lo antes da verificação.
2. Verifique a Assinatura HMAC-SHA256: Compare a assinatura fornecida no cabeçalho X-Signature com uma assinatura que você gera usando sua DIDIT_WEBHOOK_SECRET e o corpo da requisição bruto.
3. Valide o Timestamp: Verifique o cabeçalho X-Timestamp para garantir que a requisição seja recente (por exemplo, dentro de 5 minutos) para prevenir ataques de replay.
4. Analise o JSON e Processe: Se a verificação for aprovada, 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. Implante Seu Worker

Assim que seu código estiver pronto, implante-o no Cloudflare:

npx wrangler deploy

Após a implantação, o Cloudflare fornecerá uma URL para o seu Worker. Este é o endpoint que você configurará em seu Console Didit para receber webhooks.

Configurando o Didit para Enviar Webhooks

Com seu Cloudflare Worker seguro implantado, o passo final é informar ao Didit onde enviar suas notificações em tempo real:

1. Volte ao seu Console Didit.
2. Navegue até Workflows e selecione o fluxo de trabalho que deseja configurar (por exemplo, seu fluxo de trabalho KYC que usa a Verificação de ID do Didit e a Liveness Passiva e Ativa).
3. Nas configurações do fluxo de trabalho, encontre a configuração de URL do Webhook.
4. Insira a URL do seu Cloudflare Worker implantado.
5. Salve suas alterações.

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

Como o Didit Ajuda

O Didit foi projetado com segurança e experiência do desenvolvedor em seu núcleo. Nossa plataforma de identidade nativa de IA oferece uma arquitetura modular que permite compor fluxos de trabalho de verificação complexos com facilidade. Quando se trata de webhooks, o Didit simplifica o processo ao:

• Fornecer Notificações Seguras de Webhook: Todos os webhooks Didit são assinados com uma assinatura HMAC-SHA256 e incluem um timestamp, garantindo a autenticidade e integridade dos dados que você recebe. Isso é crucial para produtos como Verificação de ID, Correspondência Facial 1:1 e Triagem AML, onde a precisão dos dados é primordial.
• Atualizações em Tempo Real: Receba notificações instantâneas para cada etapa do processo de verificação, permitindo que sua aplicação reaja imediatamente aos resultados da verificação do usuário.
• Dados Abrangentes: Os 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 Liveness Passiva e Ativa, Verificação de Telefone e E-mail e Comprovante de Endereço.
• Abordagem Desenvolvedor-First: O Didit oferece um sandbox instantâneo, documentação pública clara e APIs limpas, tornando a integração simples. Nosso nível gratuito de KYC Core e modelo de pagamento por verificação bem-sucedida, sem taxas de configuração, facilitam o início e a escalabilidade.

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

Pronto para Começar?

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

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