Como Criar um Handler de Webhook em Go para Verificação de Identidade (PT-PT)

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 utilizadores e sistemas de prevenção de fraude.

Gestão Robusta de ErrosA implementação de mecanismos de repetição, filas de mensagens não entregues (dead-letter queues) e registo abrangente é vital para manter a integridade dos dados e a fiabilidade do sistema ao processar eventos de webhook assíncronos.

A Segurança é FundamentalValide sempre as assinaturas dos webhooks, utilize HTTPS e sanitize os dados de entrada para proteger contra adulterações e acessos não autorizados, 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 a Verificação de ID até ao Rastreio AML, com KYC Core Gratuito.

No panorama moderno da identidade digital, o feedback em tempo real não é apenas um luxo; é uma necessidade. Seja para integrar novos utilizadores, prevenir fraudes ou garantir a conformidade, conhecer o resultado de uma verificação de identidade no momento em que acontece permite uma ação imediata e uma experiência de utilizador mais fluida. É aqui que os webhooks se destacam. Os webhooks fornecem um mecanismo poderoso para que as plataformas de verificação de identidade notifiquem a sua aplicação sobre eventos à medida que ocorrem, eliminando a necessidade de sondagem constante.

Esta publicação irá guiá-lo na construção de um handler de webhook robusto e seguro em Go, especificamente adaptado para processar eventos de verificação de identidade. As fortes funcionalidades de concorrência e desempenho de Go tornam-no uma excelente escolha para lidar com a natureza assíncrona dos webhooks.

Compreender os Webhooks para Verificação de Identidade

Antes de mergulharmos no código, vamos esclarecer o que são os webhooks e porque são críticos para a verificação de identidade. Um webhook é essencialmente uma callback HTTP definida pelo utilizador. Em vez da sua aplicação estar continuamente a pedir atualizações a um serviço de verificação de identidade (sondagem), o serviço envia um pedido HTTP POST para um URL que você fornece sempre que um evento específico acontece. Para a verificação de identidade, estes eventos podem incluir:

• A digitalização do documento de identificação de um utilizador está completa.
• A deteção de vivacidade é aprovada ou falha.
• O rastreio AML retorna uma correspondência.
• Um fluxo de trabalho de verificação completo atinge um estado final (por exemplo, aprovado, rejeitado, revisão manual).

Receber estes eventos em tempo real permite que a sua aplicação atualize os estados dos utilizadores, desencadeie processos a jusante ou notifique os administradores sem demora. Por exemplo, assim que a Verificação de ID e as verificações de Vivacidade Passiva e Ativa de um utilizador são aprovadas, pode conceder-lhes acesso imediato ao seu serviço.

Configurar o seu Servidor de Webhook em Go

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

package main

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

// WebhookPayload represents the structure of an incoming webhook from an identity verification service.
// This is a simplified example; actual payloads will vary.
type WebhookPayload struct {
	Event   string `json:"event"`
	SessionID string `json:"session_id"`
	Status  string `json:"status"`
	Data    json.RawMessage `json:"data"` // Use RawMessage to defer unmarshaling of nested data
}

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
	}

	// Log the received event for now. In a real application, you'd process this.
	log.Printf("Received webhook event: %s for session %s with status %s", payload.Event, payload.SessionID, payload.Status)

	// Respond with a 200 OK to acknowledge receipt. Most webhook senders expect this.
	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 a escutar na porta 8080 e lida com pedidos POST para o endpoint /webhook. Ele lê o payload JSON de entrada, desmarshala-o para uma estrutura WebhookPayload e regista o evento. Crucialmente, ele responde com um código de status 200 OK para confirmar o recebimento bem-sucedido do webhook. Não responder com um 200 OK pode fazer com que o remetente tente novamente a entrega, levando a processamento duplicado.

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

A segurança é fundamental ao lidar com dados sensíveis de verificação de identidade. Deve garantir que os webhooks recebidos são legítimos e não foram adulterados. Os dois principais mecanismos para isso são:

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

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

// ... (previous imports and WebhookPayload struct)

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

const webhookSecret = "YOUR_DIDIT_WEBHOOK_SECRET" // Replace with your actual secret

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) {
	// ... (method check and body reading)

	signature := r.Header.Get("X-Didit-Signature") // Or similar header name from your provider
	if signature == "" {
		http.Error(w, "Missing signature header", http.StatusUnauthorized)
		return
	}

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

	// ... (payload unmarshaling and processing)
}

Lembre-se de armazenar a sua webhookSecret de forma segura, idealmente em variáveis de ambiente ou num sistema de gestão de segredos, não codificada na sua aplicação.

Robustez: Processamento Assíncrono e Retries

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

// ... (previous code)

func processWebhookAsync(payload WebhookPayload) {
	// In a real application, this might involve:
	// - Storing the event in a database
	// - Pushing to a message queue (e.g., Kafka, RabbitMQ)
	// - Calling other internal services
	log.Printf("Asynchronously processing event: %s for session %s", payload.Event, payload.SessionID)
	// Simulate work
	// time.Sleep(5 * time.Second)
	log.Printf("Finished async processing for session %s", payload.SessionID)
}

func webhookHandler(w http.ResponseWriter, r *http.Request) {
	// ... (signature verification and payload unmarshaling)

	// Acknowledge receipt immediately.
	w.WriteHeader(http.StatusOK)
	fmt.Fprint(w, "Webhook received successfully")

	// Process asynchronously to avoid blocking the HTTP response.
	go processWebhookAsync(payload)
}

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

Como a Didit Ajuda

A Didit, como plataforma de identidade nativa de IA e focada no desenvolvedor, 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 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, Rastreio e Monitorização AML, Comprovativo de Morada e até Estimativa de Idade com preservação da privacidade. Cada passo destes fluxos de trabalho, e o resultado final, pode desencadear eventos de webhook diretamente para a sua aplicação Go.

Com a Didit, configura o seu URL de webhook na Consola de Negócios, e a Didit envia atualizações automáticas para o seu endpoint configurado à medida que o utilizador avança e quando o resultado final da verificação está pronto. A Didit fornece payloads de webhook robustos, muitas vezes incluindo um cabeçalho de assinatura para que verifique a autenticidade, garantindo a segurança da sua integração. Isto permite-lhe construir respostas sofisticadas e automatizadas aos resultados da verificação, acelerando o onboarding de utilizadores, melhorando a deteção de fraude e otimizando os processos de conformidade sem intervenção manual.

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

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.