Desenvolva um Handler Go para Webhooks de Verificação de Identidade (PT-BR)

Automação em Tempo RealWebhooks permitem respostas instantâneas e orientadas por eventos aos resultados da verificação de identidade, cruciais para o onboarding dinâmico de usuários e sistemas de prevenção de fraude.

Tratamento Robusto de ErrosA implementação de mecanismos de retentativa, filas de mensagens mortas e registro abrangente é vital para manter a integridade dos dados e a confiabilidade do sistema ao processar eventos assíncronos de webhook.

Segurança é FundamentalSempre valide as assinaturas de webhook, use HTTPS e sanitize os dados de entrada para proteger contra adulteração e acesso não autorizado, salvaguardando informações de identidade sensíveis.

Didit Simplifica a IntegraçãoA plataforma modular e API-first da Didit oferece suporte abrangente a webhooks, permitindo que os desenvolvedores configurem facilmente notificações em tempo real para todos os eventos de verificação de identidade, desde Verificação de ID até Triagem AML, com KYC Essencial Gratuito.

No cenário moderno da identidade digital, o feedback em tempo real não é apenas um luxo; é uma necessidade. Seja para integrar novos usuários, prevenir fraudes ou garantir a conformidade, saber o resultado de uma verificação de identidade no momento em que ela acontece permite ações imediatas e uma experiência de usuário mais fluida. É aqui que os webhooks brilham. Os webhooks fornecem um mecanismo poderoso para plataformas de verificação de identidade notificarem seu aplicativo sobre eventos à medida que ocorrem, eliminando a necessidade de polling constante.

Esta postagem do blog o guiará na construção de um handler de webhook robusto e seguro em Go, especificamente adaptado para processar eventos de verificação de identidade. Os fortes recursos de concorrência e desempenho do Go o tornam uma excelente escolha para lidar com a natureza assíncrona dos webhooks.

Entendendo os Webhooks para Verificação de Identidade

Antes de mergulhar no código, vamos esclarecer o que são webhooks e por que eles são críticos para a verificação de identidade. Um webhook é essencialmente um callback HTTP definido pelo usuário. Em vez de seu aplicativo perguntar continuamente a um serviço de verificação de identidade por atualizações (polling), o serviço envia uma solicitação HTTP POST para um URL que você fornece sempre que um evento específico acontece. Para verificação de identidade, esses eventos podem incluir:

• A digitalização do documento de identidade de um usuário foi concluída.
• A detecção de vivacidade é aprovada ou reprovada.
• A triagem AML retorna uma correspondência.
• Um fluxo de trabalho de verificação completo atinge um status final (por exemplo, aprovado, rejeitado, revisão manual).

Receber esses eventos em tempo real permite que seu aplicativo atualize o status dos usuários, acione processos subsequentes ou notifique administradores sem demora. Por exemplo, uma vez que a Verificação de ID e as verificações de Vivacidade Passiva e Ativa de um usuário são aprovadas, você pode conceder-lhe acesso imediato ao seu serviço.

Configurando seu Servidor Webhook em Go

Construir um handler de webhook em Go envolve configurar um servidor HTTP simples que escuta solicitações POST de entrada. Usaremos o pacote padrão net/http do Go para isso. Primeiro, vamos criar uma estrutura básica de servidor.

package main

import (
	"encoding/json"
	"fmt"
	"io/ioutil"
	"log"
	"net/http"
)

// WebhookPayload representa a estrutura de um webhook de entrada de um serviço de verificação de identidade.
// Este é um exemplo simplificado; payloads reais variarão.
type WebhookPayload struct {
	Event   string `json:"event"`
	SessionID string `json:"session_id"`
	Status  string `json:"status"`
	Data    json.RawMessage `json:"data"` // Use RawMessage para adiar o unmarshaling de dados aninhados
}

func webhookHandler(w http.ResponseWriter, r *http.Request) {
	if r.Method != http.MethodPost {
		http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
		return
	}

	body, err := ioutil.ReadAll(r.Body)
	if err != nil {
		http.Error(w, "Error reading request body", http.StatusInternalServerError)
		return
	}

	var payload WebhookPayload
	err = json.Unmarshal(body, &payload)
	if err != nil {
		http.Error(w, "Error unmarshaling JSON payload", http.StatusBadRequest)
		log.Printf("Failed to unmarshal webhook: %v, Body: %s", err, body)
		return
	}

	// Registre o evento recebido por enquanto. Em uma aplicação real, você o processaria.
	log.Printf("Received webhook event: %s for session %s with status %s", payload.Event, payload.SessionID, payload.Status)

	// Responda com um 200 OK para confirmar o recebimento. A maioria dos remetentes de webhook espera isso.
	w.WriteHeader(http.StatusOK)
	fmt.Fprint(w, "Webhook received successfully")
}

func main() {
	http.HandleFunc("/webhook", webhookHandler)

	port := ":8080"
	log.Printf("Webhook server starting on port %s\n", port)
	log.Fatal(http.ListenAndServe(port, nil))
}

Este exemplo básico configura um servidor HTTP escutando na porta 8080 e lida com solicitações POST para o endpoint /webhook. Ele lê o payload JSON de entrada, o decodifica em uma struct WebhookPayload e registra o evento. Crucialmente, ele responde com um código de status 200 OK para confirmar o recebimento bem-sucedido do webhook. A falha em responder com um 200 OK pode fazer com que o remetente tente a entrega novamente, levando a processamento duplicado.

Garantindo a Segurança: Verificação de Assinatura e HTTPS

A segurança é primordial ao lidar com dados sensíveis de verificação de identidade. Você deve garantir que os webhooks de entrada sejam legítimos e não tenham sido adulterados. Os dois mecanismos principais para isso são:

1. HTTPS: Sempre exponha seu endpoint de webhook via HTTPS para criptografar os dados em trânsito, prevenindo a interceptação.
2. Verificação de Assinatura: A maioria dos provedores de verificação de identidade respeitáveis, incluindo a Didit, envia uma assinatura ou hash nos cabeçalhos da solicitação (por exemplo, X-Didit-Signature). Você deve usar uma chave secreta compartilhada para calcular seu próprio hash do corpo da solicitação bruta e compará-lo com a assinatura de entrada. Se não corresponderem, o webhook provavelmente é fraudulento ou comprometido.

Aqui está um exemplo de como você pode adicionar a verificação de assinatura ao seu handler:

// ... (imports anteriores e struct WebhookPayload)

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	// ... outros imports
)

const webhookSecret = "YOUR_DIDIT_WEBHOOK_SECRET" // Substitua pela sua chave secreta real

func verifySignature(body []byte, signature string) bool {
	hmacHash := hmac.New(sha256.New, []byte(webhookSecret))
	hmacHash.Write(body)
	expectedMAC := hmacHash.Sum(nil)

	decodedSignature, err := hex.DecodeString(signature)
	if err != nil {
		return false
	}

	return hmac.Equal(decodedSignature, expectedMAC)
}

func webhookHandler(w http.ResponseWriter, r *http.Request) {
	// ... (verificação de método e leitura do corpo)

	signature := r.Header.Get("X-Didit-Signature") // Ou nome de cabeçalho similar do seu provedor
	if signature == "" {
		http.Error(w, "Missing signature header", http.StatusUnauthorized)
		return
	}

	if !verifySignature(body, signature) {
		http.Error(w, "Invalid signature", http.StatusUnauthorized)
		return
	}

	// ... (decodificação e processamento do payload)
}

Lembre-se de armazenar seu webhookSecret de forma segura, idealmente em variáveis de ambiente ou em um sistema de gerenciamento de segredos, não codificado em seu aplicativo.

Robustez: Processamento Assíncrono e Retentativas

Os webhooks devem ser processados rapidamente para evitar timeouts e retentativas do remetente. Para tarefas complexas ou demoradas, é melhor descarregar o processamento para uma goroutine separada ou fila de mensagens. Seu handler de webhook deve se concentrar principalmente em receber, validar e reconhecer o evento.

// ... (código anterior)

func processWebhookAsync(payload WebhookPayload) {
	// Em uma aplicação real, isso pode envolver:
	// - Armazenar o evento em um banco de dados
	// - Enviar para uma fila de mensagens (por exemplo, Kafka, RabbitMQ)
	// - Chamar outros serviços internos
	log.Printf("Asynchronously processing event: %s for session %s", payload.Event, payload.SessionID)
	// Simular trabalho
	// time.Sleep(5 * time.Second)
	log.Printf("Finished async processing for session %s", payload.SessionID)
}

func webhookHandler(w http.ResponseWriter, r *http.Request) {
	// ... (verificação de assinatura e decodificação do payload)

	// Confirme o recebimento imediatamente.
	w.WriteHeader(http.StatusOK)
	fmt.Fprint(w, "Webhook received successfully")

	// Processe assincronamente para evitar bloquear a resposta HTTP.
	go processWebhookAsync(payload)
}

Além disso, serviços externos podem falhar ocasionalmente. Implemente mecanismos de retentativa para quaisquer chamadas subsequentes feitas durante o processamento assíncrono. Considere usar uma fila de mensagens mortas (DLQ) para eventos que falham repetidamente, permitindo inspeção manual e reprocessamento.

Como a Didit Ajuda

A Didit, como uma plataforma de identidade nativa de IA e focada em desenvolvedores, torna a integração de eventos de verificação de identidade em tempo real simples e segura. A arquitetura modular da Didit é construída para orquestração, o que significa que você pode definir fluxos de trabalho complexos combinando Verificação de ID (OCR, MRZ, códigos de barras), Vivacidade Passiva e Ativa, Correspondência Facial 1:1, Triagem e Monitoramento AML, Comprovante de Endereço e até mesmo Estimativa de Idade com preservação da privacidade. Cada etapa desses fluxos de trabalho, e o resultado final, pode acionar eventos de webhook diretamente para seu aplicativo Go.

Com a Didit, você configura seu URL de webhook no Business Console, e a Didit envia atualizações automáticas para o seu endpoint configurado à medida que o usuário avança e quando o resultado final da verificação está pronto. A Didit fornece payloads de webhook robustos, frequentemente incluindo um cabeçalho de assinatura para você verificar a autenticidade, garantindo a segurança de sua integração. Isso permite que você construa respostas sofisticadas e automatizadas aos resultados da verificação, acelerando o onboarding de usuários, aprimorando a detecção de fraudes e otimizando os processos de conformidade sem intervenção manual.

As vantagens da Didit, como o KYC Essencial Gratuito e a ausência de taxas de configuração, juntamente com suas APIs limpas e documentação abrangente, capacitam você a construir soluções de identidade poderosas e orientadas por eventos com máxima eficiência. Quer você esteja usando Links de Verificação para integração sem código ou aproveitando diretamente a API, o sistema de webhook da Didit garante que você esteja sempre em sincronia com as jornadas de verificação de seus usuários.

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.