Guia do Desenvolvedor: Criando Listeners Webhook Personalizados para KYC (PT-BR)

Configuração Segura de WebhookImplemente endpoints webhook seguros com verificação de assinatura HMAC-SHA256 e validação de timestamp para prevenir ataques de repetição e garantir a integridade dos dados do seu provedor KYC.

Processamento KYC em Tempo RealAproveite os webhooks para receber notificações instantâneas sobre o status da sessão de verificação de identidade, permitindo atualizações imediatas nos perfis dos usuários e otimizando os fluxos de integração.

Tratamento de Erros RobustoProjete seu listener webhook com tratamento de erros abrangente, incluindo retentativas e filas de mensagens mortas (dead-letter queues), para gerenciar problemas transitórios e garantir que nenhum dado KYC crítico seja perdido.

Integração Simplificada da DiditA Didit simplifica a configuração de webhooks com documentação API clara, versões configuráveis e rotação automática de segredos, facilitando a integração segura e eficiente de resultados KYC em tempo real em qualquer aplicação.

O Poder do KYC em Tempo Real com Webhooks

Na economia digital acelerada de hoje, a verificação de identidade em tempo real (KYC) não é mais um luxo, mas uma necessidade. As empresas precisam integrar usuários de forma rápida e segura, verificando instantaneamente suas identidades para prevenir fraudes e cumprir regulamentações. Embora consultar uma API para atualizações de status possa funcionar, é ineficiente e pode introduzir atrasos. É aqui que os webhooks brilham. Os webhooks fornecem um mecanismo instantâneo e orientado a eventos para que seu provedor de KYC notifique sua aplicação sempre que o status de uma sessão de verificação mudar. Isso permite tomada de decisões imediata, integração de usuários mais rápida e uma experiência superior para o cliente.

Para desenvolvedores, construir um listener webhook personalizado significa assumir o controle do seu fluxo de trabalho KYC. Em vez de esperar, seu sistema reage. Seja uma verificação de identidade bem-sucedida, uma falha na verificação de vivacidade ou um alerta de triagem AML, os webhooks entregam as informações que você precisa exatamente quando precisa. A Didit, com sua plataforma nativa de IA, adota esse paradigma em tempo real, oferecendo recursos robustos de webhook que se integram perfeitamente à sua infraestrutura existente.

Configurando Seu Endpoint Webhook com a Didit

Configurar seu endpoint webhook com um provedor como a Didit é simples. A Didit permite que você configure sua URL de webhook, especifique a versão do payload (v3 é recomendada para os recursos mais recentes) e gerencie sua chave secreta diretamente através de sua API ou Console de Negócios. Essa flexibilidade garante que você possa adaptar a integração às suas necessidades específicas.

Ao configurar, você definirá a URL onde a Didit enviará as notificações. Esta URL deve ser publicamente acessível e capaz de receber requisições POST. A Didit também permite que você defina um parâmetro data_retention_months, dando-lhe controle sobre por quanto tempo os dados da sessão são armazenados, o que é crucial para conformidade. Você também pode especificar o capture_method para sessões de verificação (móvel, desktop ou ambos) e até mesmo rotacionar sua secret_shared_key para segurança aprimorada, invalidando a chave antiga imediatamente.

Por exemplo, usando a API de gerenciamento da Didit, você pode atualizar sua configuração de webhook:

PATCH /v3/webhook/
{
  "webhook_url": "https://myapp.com/webhooks/didit",
  "webhook_version": "v3",
  "capture_method": "both",
  "data_retention_months": 12
}

Esta simples chamada de API informa à Didit onde enviar suas atualizações KYC em tempo real e como formatá-las, garantindo que você receba informações críticas para processos como Verificação de ID e verificações de Vivacidade Passiva e Ativa.

Construindo um Listener Webhook Seguro e Confiável

A segurança é primordial ao lidar com dados KYC sensíveis. Seu listener webhook deve ser projetado para verificar a autenticidade e a integridade de cada requisição recebida. A Didit fornece uma secret_shared_key que você usará para validar as assinaturas do webhook. O processo geralmente envolve:

1. Recebendo a Requisição: Seu endpoint recebe uma requisição POST da Didit.
2. Extraindo a Assinatura: A Didit inclui um cabeçalho X-Signature com uma assinatura HMAC-SHA256.
3. Verificando a Assinatura: Você calculará sua própria assinatura HMAC-SHA256 usando o corpo da requisição bruta e sua secret_shared_key. Esta assinatura calculada deve corresponder àquela no cabeçalho X-Signature. Crucialmente, NÃO analise o corpo JSON antes de verificar a assinatura.
4. Validação de Timestamp: Os payloads do webhook também incluem um timestamp. Valide que este timestamp seja recente (por exemplo, dentro de 5 minutos) para prevenir ataques de repetição.
5. Processando o Payload: Uma vez verificado, você pode analisar com segurança o corpo JSON e processar os resultados KYC.

Além da segurança, a confiabilidade é fundamental. Seu listener deve ser idempotente, o que significa que processar o mesmo evento várias vezes tem o mesmo efeito que processá-lo uma vez. Implemente um tratamento de erros robusto, incluindo registro (logging), retentativas para falhas transitórias e, possivelmente, uma fila de mensagens mortas (dead-letter queue) para eventos que falham consistentemente no processamento. Isso garante que resultados críticos de verificação de identidade, incluindo aqueles de Triagem e Monitoramento AML ou Estimativa de Idade, nunca sejam perdidos.

Lidando com Eventos Webhook e Integrando com Sua Lógica Central

Uma vez que você recebeu e validou com segurança um evento webhook, o próximo passo é integrá-lo à lógica central da sua aplicação. Os webhooks da Didit fornecem informações detalhadas sobre a sessão de verificação, incluindo seu status (por exemplo, aprovado, rejeitado, pendente), o motivo do status e pontos de dados relevantes. Por exemplo, um evento de Verificação de ID bem-sucedido pode acionar uma atualização no perfil de um usuário, marcando-o como verificado e desbloqueando o acesso a certos recursos.

Considere os tipos de eventos que você pode receber:

• Sessão Concluída: O evento mais comum, indicando que uma sessão de verificação atingiu um estado final (aprovado, rejeitado ou revisão manual).
• Documento Verificado: Específico para Verificação de ID, confirmando a autenticidade do documento.
• Verificação de Vivacidade Aprovada/Reprovada: Crucial para a prevenção de fraudes, indicando o resultado de uma verificação de vivacidade.
• Alerta AML: Significa um acerto durante a Triagem AML, exigindo investigação adicional.

Seu listener deve analisar esses eventos e acionar ações apropriadas dentro do seu sistema. Isso pode envolver a atualização do status de um usuário em seu banco de dados, o envio de notificações internas ou o início de etapas adicionais em um fluxo de trabalho de integração de várias fases. A arquitetura modular da Didit significa que esses eventos podem alimentar diretamente seus fluxos de trabalho orquestrados, permitindo reações dinâmicas aos resultados da verificação.

Como a Didit Ajuda

A Didit é projetada para simplificar o complexo mundo da verificação de identidade, e seu sistema de webhook é um excelente exemplo. Como uma plataforma nativa de IA e focada no desenvolvedor, a Didit oferece APIs limpas e documentação abrangente que tornam a integração de webhooks muito fácil. Oferecemos KYC Core Gratuito, permitindo que você comece sem custos iniciais, e nossa arquitetura modular significa que você só usa e paga pelo que precisa.

Com a Didit, você se beneficia de:

• Configuração Perfeita: Configure e gerencie facilmente sua URL de webhook, versão e chave secreta através da API ou do Console de Negócios intuitivo.
• Recursos de Segurança Robustos: Suporte integrado para verificação de assinatura HMAC-SHA256 e validação de timestamp garante a integridade e autenticidade de todos os dados de webhook recebidos.
• Payloads Detalhados: Receba dados ricos e estruturados para cada evento de verificação, cobrindo produtos como Verificação de ID, Vivacidade Passiva e Ativa, Correspondência Facial 1:1, Triagem e Monitoramento AML, Comprovação de Endereço e Estimativa de Idade.
• Fluxos de Trabalho Orquestrados: Os eventos de webhook podem ser integrados perfeitamente ao construtor de fluxo de trabalho sem código da Didit, permitindo que você projete respostas automatizadas sofisticadas aos resultados da verificação.
• Sem Taxas de Configuração: Comece imediatamente e integre poderosos recursos de verificação de identidade em sua aplicação sem custos ocultos.

O compromisso da Didit em ser uma plataforma focada no desenvolvedor significa que você gasta menos tempo com o "boilerplate" de integração e mais tempo construindo recursos inovadores, tudo isso enquanto garante que seus processos KYC sejam seguros, compatíveis e extremamente rápidos.

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.