Construindo Webhook Listeners Didit com AWS Lambda e API Gateway (PT-BR)

Integração Segura de WebhooksA implementação de uma verificação robusta da assinatura de webhooks usando a chave secreta compartilhada da Didit é crucial para garantir a integridade e autenticidade dos dados recebidos da plataforma Didit, protegendo contra falsificação e adulteração.

Arquitetura Serverless EscalávelO aproveitamento do AWS Lambda e API Gateway com o Serverless Framework oferece uma solução altamente escalável e econômica para lidar com eventos de webhook da Didit, ajustando-se automaticamente a cargas variáveis sem intervenção manual.

Fluxos de Trabalho de Identidade em Tempo RealO processamento de webhooks da Didit em tempo real permite respostas imediatas aos resultados da verificação de identidade, facilitando a integração dinâmica de usuários, detecção de fraudes e ações de conformidade, aumentando a eficiência operacional.

Abordagem Developer-First da DiditA Didit simplifica o gerenciamento de webhooks com documentação de API clara, rotação fácil de chaves secretas e uma arquitetura modular, permitindo que os desenvolvedores construam e implementem rapidamente fluxos de trabalho orientados a eventos personalizados com KYC Core Gratuito e sem taxas de configuração.

O Poder dos Webhooks na Verificação de Identidade

No mundo da verificação de identidade, o feedback em tempo real é primordial. Seja você integrando novos usuários, realizando triagem AML ou verificando a idade, saber o resultado de uma sessão de verificação assim que ela acontece permite tomadas de decisão dinâmicas e experiências de usuário fluidas. É aqui que os webhooks brilham. Em vez de constantemente consultar uma API para atualizações de status, a Didit envia uma notificação automatizada para o seu endpoint especificado sempre que um evento significativo ocorre, como a conclusão de uma sessão de verificação ou a mudança de status. Este modelo baseado em push é mais eficiente, reduz a sobrecarga de chamadas de API e garante que seus sistemas estejam sempre atualizados com os resultados mais recentes da verificação de identidade.

A integração das poderosas capacidades de verificação de identidade da Didit frequentemente envolve a configuração de um listener de webhook confiável. Este listener atua como os olhos e ouvidos da sua aplicação, recebendo atualizações críticas sobre o status dos resultados de Verificação de ID, Detecção de Vivacidade ou Triagem AML. Um sistema de webhook bem implementado é a pedra angular das arquiteturas modernas, orientadas a eventos, proporcionando a agilidade necessária para responder rapidamente aos resultados da verificação e manter uma jornada de usuário tranquila.

Configurando Seu Listener de Webhook Serverless com AWS Lambda e API Gateway

Construir um listener de webhook escalável e resiliente pode ser complexo, mas com AWS Lambda e API Gateway, juntamente com o Serverless Framework, torna-se notavelmente direto. Essa abordagem serverless significa que você não precisa gerenciar nenhum servidor; a AWS cuida de toda a infraestrutura, escalando seu listener automaticamente com base na demanda. Para o nosso listener de webhook da Didit, usaremos TypeScript para segurança de tipo e produtividade do desenvolvedor.

Pré-requisitos:

• Uma conta AWS
• Node.js e npm instalados
• Serverless Framework instalado (npm install -g serverless)
• Uma conta Didit com chaves de API e um segredo de webhook (em Didit Console -> Configurações -> Chaves de API)

Configuração do Projeto:

Primeiro, crie um novo projeto Serverless:

serverless create --template aws-nodejs-typescript --path didit-webhook-listener
cd didit-webhook-listener
npm install

Agora, vamos configurar serverless.yml para definir nossa função Lambda e endpoint do API Gateway:

service: didit-webhook-listener

provider:
  name: aws
  runtime: nodejs18.x
  stage: dev
  region: us-east-1
  environment:
    DIDIT_WEBHOOK_SECRET: ${ssm:/didit/webhook/secret}

functions:
  handleDiditWebhook:
    handler: src/handler.handleDiditWebhook
    events:
      - http:
          path: webhook/didit
          method: post
          cors: true

plugins:
  - serverless-offline
  - serverless-dotenv-plugin
  - serverless-ssm-fetch

Observe que estamos buscando o DIDIT_WEBHOOK_SECRET do AWS SSM Parameter Store, o que é uma boa prática para gerenciar segredos. Você precisará armazenar seu Segredo de Webhook da Didit lá. A Didit permite que você rotacione facilmente sua chave secreta via API ou Didit Console, garantindo uma boa higiene de segurança.

Implementando o Processamento Seguro de Webhooks em TypeScript

O aspecto mais crítico de qualquer listener de webhook é a segurança. Você deve verificar se as solicitações recebidas realmente se originam da Didit e não foram adulteradas. A Didit fornece uma chave secreta compartilhada para esse fim, que você usa para validar a assinatura HMAC incluída no cabeçalho x-didit-signature do webhook.

Crie src/handler.ts:

import { APIGatewayProxyHandler } from 'aws-lambda';
import * as crypto from 'crypto';

const DIDIT_WEBHOOK_SECRET = process.env.DIDIT_WEBHOOK_SECRET || '';

export const handleDiditWebhook: APIGatewayProxyHandler = async (event) => {
  if (!event.body) {
    return { statusCode: 400, body: 'No body received' };
  }

  const signature = event.headers['x-didit-signature'];
  if (!signature) {
    console.warn('Webhook received without x-didit-signature header.');
    return { statusCode: 403, body: 'Missing signature' };
  }

  try {
    const expectedSignature = crypto
      .createHmac('sha256', DIDIT_WEBHOOK_SECRET)
      .update(event.body)
      .digest('hex');

    if (expectedSignature !== signature) {
      console.error('Webhook signature mismatch. Expected:', expectedSignature, 'Received:', signature);
      return { statusCode: 403, body: 'Invalid signature' };
    }

    const payload = JSON.parse(event.body);
    console.log('Successfully verified and parsed Didit webhook:', payload);

    // Implemente sua lógica de negócios aqui com base no payload do webhook
    // Exemplos: atualizar status do usuário, acionar ações adicionais, armazenar resultados
    // Por exemplo, se for uma conclusão de Verificação de ID:
    // if (payload.event_type === 'session.completed' && payload.data.workflow_type === 'kyc') {
    //   console.log('Sessão KYC Concluída para vendor_data:', payload.data.vendor_data);
    //   // Processar resultados KYC, atualizar perfil do usuário, etc.
    // }

    return { statusCode: 200, body: 'Webhook received and processed' };
  } catch (error) {
    console.error('Error processing webhook:', error);
    return { statusCode: 500, body: 'Internal server error' };
  }
};

Neste código, calculamos um hash HMAC SHA256 do corpo da solicitação bruta usando seu DIDIT_WEBHOOK_SECRET e o comparamos com o cabeçalho x-didit-signature fornecido pela Didit. Se eles não coincidirem, a solicitação é rejeitada, impedindo acesso não autorizado ou eventos falsificados. Este processo de verificação robusto é essencial para manter a segurança e a integridade de seus fluxos de trabalho de verificação de identidade, especialmente ao lidar com dados sensíveis dos serviços de Verificação de ID, Face Match ou Triagem AML da Didit.

Configurando a Didit para Enviar Webhooks

Depois que sua função Lambda for implantada e você tiver uma URL de endpoint do API Gateway, o passo final é informar à Didit onde enviar seus webhooks. Isso pode ser feito facilmente através da API de Gerenciamento da Didit ou pelo Console de Negócios da Didit.

Via API de Gerenciamento da Didit:

Você pode atualizar programaticamente sua configuração de webhook usando o endpoint PATCH /v3/webhook/. Isso permite que você defina sua webhook_url, especifique uma webhook_version (v3 é recomendado) e até mesmo rotacione sua secret_shared_key com segurança.

curl -X PATCH https://verification.didit.me/v3/webhook/ \
  -H "Content-Type: application/json" \
  -H "x-api-key: SUA_CHAVE_API_DIDIT" \
  -d '{
    "webhook_url": "SEU_ENDPOINT_API_GATEWAY",
    "webhook_version": "v3"
  }'

Substitua SUA_CHAVE_API_DIDIT pela sua chave de API Didit real e SEU_ENDPOINT_API_GATEWAY pela URL fornecida pelo AWS API Gateway após implantar sua função Serverless.

Via Console de Negócios da Didit:

Alternativamente, navegue até o Console da Didit, vá em Configurações -> Webhooks e simplesmente cole a URL do seu endpoint do API Gateway no campo designado. Você também pode visualizar e rotacionar sua chave secreta de webhook aqui. O design modular da Didit garante que a configuração dessas integrações vitais seja simples, permitindo que você se concentre na construção de sua aplicação principal.

Como a Didit Ajuda

A Didit oferece uma plataforma de identidade nativa de IA e com foco no desenvolvedor que torna a integração de verificação de identidade avançada simples e segura. Nossa arquitetura modular permite que você escolha os componentes exatos que precisa, desde Verificação de ID (OCR, MRZ, códigos de barras) e Detecção de Vivacidade Passiva e Ativa até Face Match 1:1, Triagem e Monitoramento AML e Estimativa de Idade. Ao oferecer KYC Core Gratuito e sem taxas de configuração, a Didit capacita empresas de todos os portes a implementar soluções de identidade robustas sem custos proibitivos.

Nossa documentação de API abrangente e ambiente sandbox instantâneo garantem que os desenvolvedores possam começar rapidamente, e nosso sistema de webhook, como demonstrado, é projetado para confiabilidade e segurança. Com a Didit, você obtém acesso a uma rede de verificação global, fluxos de trabalho orquestrados e dados de identidade estruturados, tudo entregue por meio de APIs limpas. Isso significa que você pode construir com confiança listeners de webhook personalizados que se integram perfeitamente com o poderoso backend da Didit, garantindo atualizações em tempo real para todas as suas necessidades de verificação de identidade.

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.