FastAPI: Middleware para Pontuação de Risco de Identidade em Tempo Real com Didit (PT-BR)

A Pontuação de Risco em Tempo Real é Essencial. Aplicações modernas exigem avaliação imediata do risco de identidade para combater fraudes e garantir a conformidade de forma eficaz.

O Manuseio Seguro de Webhooks é Fundamental. A implementação robusta de verificação de assinatura e checagem de timestamp para webhooks recebidos previne adulterações e ataques de repetição, crucial para manter a integridade dos dados.

Middleware FastAPI Otimiza a Integração. Utilizar as capacidades de middleware do FastAPI permite o processamento centralizado e eficiente de eventos assíncronos de webhook, integrando-se perfeitamente ao fluxo da sua aplicação.

Didit Potencializa a Orquestração Inteligente de Identidade. Didit oferece a verificação de identidade nativa de IA e a infraestrutura de webhook, fornecendo notificações em tempo real e sinais de risco abrangentes para embasar as decisões de segurança da sua aplicação.

No cenário digital atual, a velocidade e a precisão da verificação de identidade impactam diretamente a postura de segurança e a experiência do usuário de uma aplicação. À medida que os negócios crescem, a necessidade de pontuação de risco em tempo real se torna primordial, permitindo ação imediata contra atividades fraudulentas e garantindo a conformidade com as normas regulatórias. Integrar uma plataforma avançada de verificação de identidade como o Didit ao seu backend, especialmente usando um framework moderno como o FastAPI, pode aprimorar significativamente suas defesas.

Este post do blog irá guiá-lo na construção de um middleware FastAPI robusto para processar os webhooks do Didit para pontuação de risco de identidade em tempo real. Abordaremos a recepção segura de webhooks, verificação de assinatura e como integrar esses sinais de risco críticos à lógica da sua aplicação.

O Poder dos Webhooks para Sinais de Identidade em Tempo Real

Webhooks são a base da comunicação assíncrona moderna, permitindo que os serviços enviem notificações em tempo real para outras aplicações quando eventos específicos ocorrem. Para a verificação de identidade, isso significa que, assim que um usuário conclui uma etapa de verificação, ou uma avaliação de risco é finalizada, o Didit pode informar imediatamente sua aplicação. Esse feedback em tempo real é crucial para a pontuação de risco dinâmica, permitindo que você:

• Atualize instantaneamente perfis de usuário: Marque usuários como verificados ou sinalize-os para revisão com base no resultado da Verificação de ID ou Triagem AML.
• Acione fluxos de trabalho condicionais: Se um usuário falhar em uma verificação de detecção de vivacidade ou for sinalizado durante a Triagem AML, você pode iniciar imediatamente um processo de revisão mais aprofundado ou bloquear o acesso.
• Aprimore a detecção de fraudes: Combine os sinais de risco do Didit, como Análise de IP ou resultados de Verificação de Telefone, com seus modelos internos de fraude para uma avaliação mais abrangente.

Os webhooks do Didit fornecem payloads JSON detalhados com os resultados de várias verificações, incluindo as de Verificação de ID, Vivacidade Passiva e Ativa, Correspondência Facial 1:1, Triagem e Monitoramento AML, Comprovante de Endereço e Verificação de Telefone e E-mail. Esses pontos de dados ricos são inestimáveis para construir um perfil de risco em tempo real para cada usuário.

Protegendo Seu Endpoint de Webhook com Middleware FastAPI

Receber webhooks com segurança é inegociável. Atores mal-intencionados podem tentar enviar eventos falsos ou reproduzir eventos antigos, levando a dados comprometidos ou ações incorretas. Os webhooks do Didit incluem uma assinatura HMAC-SHA256 e um timestamp, que são essenciais para verificar a autenticidade e a integridade de cada solicitação recebida. O middleware FastAPI é um excelente local para implementar essas verificações de segurança de forma centralizada.

Aqui está um esboço conceitual de como você estruturaria seu middleware FastAPI:

import hmac
import hashlib
import time
from fastapi import FastAPI, Request, HTTPException
from starlette.middleware.base import BaseHTTPMiddleware
from starlette.responses import JSONResponse

WEBHOOK_SECRET = "YOUR_DIDIT_WEBHOOK_SECRET" # Obtenha isso do Didit Console -> Chaves de API

class DiditWebhookSignatureMiddleware(BaseHTTPMiddleware):
    async def dispatch(self, request: Request, call_next):
        if request.url.path == "/api/webhooks/didit":
            signature = request.headers.get("X-Signature")
            timestamp = request.headers.get("X-Timestamp")

            if not signature or not timestamp:
                raise HTTPException(status_code=401, detail="Assinatura ou timestamp do webhook ausente")

            # 1. Verificar a "frescura" do Timestamp (ex: dentro de 5 minutos)
            try:
                request_time = int(timestamp)
                if abs(time.time() - request_time) > 300: # 300 segundos = 5 minutos
                    raise HTTPException(status_code=401, detail="Timestamp do webhook muito antigo ou muito novo")
            except ValueError:
                raise HTTPException(status_code=401, detail="Formato de timestamp inválido")

            # 2. Reconstruir o payload assinado
            body = await request.body()
            signed_payload = f"{timestamp}.{body.decode('utf-8')}"

            # 3. Calcular a assinatura esperada
            expected_signature = hmac.new(
                WEBHOOK_SECRET.encode('utf-8'),
                signed_payload.encode('utf-8'),
                hashlib.sha256
            ).hexdigest()

            # 4. Comparar assinaturas
            if not hmac.compare_digest(expected_signature, signature):
                raise HTTPException(status_code=401, detail="Assinatura do webhook inválida")

            # Se a assinatura e o timestamp forem válidos, prossiga
            request.state.didit_webhook_body = body.decode('utf-8') # Armazenar para processamento posterior
        return await call_next(request)

app = FastAPI()
app.add_middleware(DiditWebhookSignatureMiddleware)

@app.post("/api/webhooks/didit")
async def handle_didit_webhook(request: Request):
    # O corpo do webhook já foi verificado e está disponível em request.state
    payload = json.loads(request.state.didit_webhook_body)
    # Processar payload para pontuação de risco, atualizar status do usuário, etc.
    print("Webhook Didit válido recebido:", payload)
    return JSONResponse({"status": "success"})

Este middleware garante que cada solicitação de webhook do Didit que atinge seu endpoint /api/webhooks/didit seja autenticada e "fresca" antes mesmo que a lógica da sua aplicação veja o payload. Esta é uma camada crítica de defesa contra vários vetores de ataque.

Integrando Sinais de Risco em Tempo Real à Lógica da Sua Aplicação

Uma vez que o payload do webhook é verificado e analisado, sua aplicação pode extrair as informações necessárias para atualizar as pontuações de risco do usuário ou acionar ações específicas. A documentação do Didit Full Flow da API descreve a estrutura abrangente desses payloads, incluindo session_id, vendor_data (seu ID de usuário interno) e os resultados detalhados de cada etapa de verificação.

Por exemplo, se um usuário passar por Verificação de ID e Detecção de Vivacidade, o payload do webhook conterá o status dessas verificações. Você pode definir uma pontuação de risco com base em:

• Verificação de ID bem-sucedida: Diminui a pontuação de risco.
• Detecção de Vivacidade falha: Aumenta significativamente a pontuação de risco, potencialmente acionando um congelamento de conta.
• Acerto na Triagem AML (PEP/Sanções): Risco alto, exigindo revisão manual imediata.
• Número de telefone descartável detectado (da Verificação de Telefone): Risco moderado, pode indicar intenção fraudulenta.

A função do seu manipulador de webhook é interpretar esses sinais e atualizar o estado interno do seu usuário ou perfil de risco de acordo. Isso pode envolver a atualização de um campo user_status em seu banco de dados, a adição de uma bandeira para revisão manual ou até mesmo a integração com um sistema dedicado de gerenciamento de fraudes.

Como o Didit Ajuda

Didit é a plataforma de identidade nativa de IA e "developer-first" projetada para tornar a pontuação de risco de identidade em tempo real contínua e eficiente. Nossa arquitetura modular permite que você componha fluxos de trabalho de verificação que atendam precisamente às suas necessidades, desde a Verificação de ID básica até a Triagem AML avançada e a detecção de Vivacidade Passiva e Ativa. Fornecemos recursos robustos de webhook, garantindo que suas aplicações recebam notificações seguras e em tempo real sobre os resultados da verificação.

Com o Didit, você se beneficia de:

• KYC Essencial Gratuito: Comece com a verificação de identidade essencial sem custo, permitindo que você construa e teste sua integração sem investimento inicial.
• Inteligência Nativa de IA: Aproveite a IA de ponta para detecção superior de fraudes, detecção de vivacidade e análise de documentos, fornecendo sinais de risco precisos.
• Abordagem "Developer-First": APIs limpas, documentação abrangente e um sandbox instantâneo tornam a integração com frameworks como o FastAPI simples e rápida.
• Fluxos de Trabalho Orquestrados: Defina fluxos de verificação complexos com um motor sem código, permitindo que você se adapte a cenários de risco em evolução sem alterações de código.
• Cobertura Global: Verifique identidades em todo o mundo com suporte para diversos tipos de documentos e requisitos de conformidade regionais.

Ao aproveitar os produtos de Verificação de Telefone e E-mail, Verificação de ID e Triagem e Monitoramento AML do Didit, combinados com nossa infraestrutura segura de webhook, você pode construir um sistema de pontuação de risco de identidade altamente responsivo e resiliente em sua aplicação FastAPI. Nossa plataforma oferece os dados em tempo real de que você precisa para tomar decisões informadas e proteger seu negócio.

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.