Crear un controlador Go Webhook para eventos de verificación de identidad (ES)

Automatización en tiempo realLos webhooks permiten respuestas instantáneas y basadas en eventos a los resultados de la verificación de identidad, crucial para la incorporación dinámica de usuarios y los sistemas de prevención de fraude.

Manejo robusto de erroresLa implementación de mecanismos de reintento, colas de mensajes fallidos y registro exhaustivo es vital para mantener la integridad de los datos y la fiabilidad del sistema al procesar eventos de webhook asincrónicos.

La seguridad es primordialSiempre valide las firmas de webhook, use HTTPS y sanee los datos entrantes para protegerse contra la manipulación y el acceso no autorizado, salvaguardando la información de identidad sensible.

Didit simplifica la integraciónLa plataforma modular y API-first de Didit proporciona soporte integral para webhooks, permitiendo a los desarrolladores configurar fácilmente notificaciones en tiempo real para todos los eventos de verificación de identidad, desde la verificación de ID hasta el cribado AML, con KYC Core gratuito.

En el panorama moderno de la identidad digital, la retroalimentación en tiempo real no es solo un lujo; es una necesidad. Ya sea que esté incorporando nuevos usuarios, previniendo el fraude o asegurando el cumplimiento, conocer el resultado de una verificación de identidad en el momento en que ocurre permite una acción inmediata y una experiencia de usuario más fluida. Aquí es donde los webhooks brillan. Los webhooks proporcionan un potente mecanismo para que las plataformas de verificación de identidad notifiquen a su aplicación sobre los eventos a medida que ocurren, eliminando la necesidad de un sondeo constante.

Esta publicación de blog lo guiará a través de la construcción de un controlador de webhook robusto y seguro en Go, específicamente diseñado para procesar eventos de verificación de identidad. Las sólidas características de concurrencia y el rendimiento de Go lo convierten en una excelente opción para manejar la naturaleza asincrónica de los webhooks.

Comprendiendo los Webhooks para la Verificación de Identidad

Antes de sumergirnos en el código, aclaremos qué son los webhooks y por qué son críticos para la verificación de identidad. Un webhook es esencialmente una devolución de llamada HTTP definida por el usuario. En lugar de que su aplicación pregunte continuamente a un servicio de verificación de identidad sobre actualizaciones (sondeo), el servicio envía una solicitud HTTP POST a una URL que usted proporciona cada vez que ocurre un evento específico. Para la verificación de identidad, estos eventos podrían incluir:

• Se completa el escaneo del documento de identificación de un usuario.
• La detección de vida pasa o falla.
• El cribado AML arroja una coincidencia.
• Un flujo de trabajo de verificación completo alcanza un estado final (por ejemplo, aprobado, rechazado, revisión manual).

Recibir estos eventos en tiempo real permite a su aplicación actualizar los estados de los usuarios, activar procesos posteriores o notificar a los administradores sin demora. Por ejemplo, una vez que la verificación de identificación de un usuario y los controles de vitalidad pasivos y activos son aprobados, puede otorgarles acceso inmediato a su servicio.

Configurando su Servidor Webhook en Go

Construir un controlador de webhook en Go implica configurar un servidor HTTP simple que escuche las solicitudes POST entrantes. Usaremos el paquete estándar net/http de Go para esto. Primero, creemos una estructura de servidor básica.

package main

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

// WebhookPayload representa la estructura de un webhook entrante de un servicio de verificación de identidad.
// Este es un ejemplo simplificado; las cargas útiles reales variarán.
type WebhookPayload struct {
	Event   string `json:"event"`
	SessionID string `json:"session_id"`
	Status  string `json:"status"`
	Data    json.RawMessage `json:"data"` // Usar RawMessage para aplazar el "unmarshaling" de datos anidados
}

func webhookHandler(w http.ResponseWriter, r *http.Request) {
	if r.Method != http.MethodPost {
		http.Error(w, "Método no permitido", http.StatusMethodNotAllowed)
		return
	}

	body, err := ioutil.ReadAll(r.Body)
	if err != nil {
		http.Error(w, "Error al leer el cuerpo de la solicitud", http.StatusInternalServerError)
		return
	}

	var payload WebhookPayload
	err = json.Unmarshal(body, &payload)
	if err != nil {
		http.Error(w, "Error al decodificar la carga útil JSON", http.StatusBadRequest)
		log.Printf("Fallo al decodificar el webhook: %v, Cuerpo: %s", err, body)
		return
	}

	// Por ahora, registra el evento recibido. En una aplicación real, lo procesarías.
	log.Printf("Evento de webhook recibido: %s para la sesión %s con estado %s", payload.Event, payload.SessionID, payload.Status)

	// Responde con un 200 OK para acusar recibo. La mayoría de los remitentes de webhook esperan esto.
	w.WriteHeader(http.StatusOK)
	fmt.Fprint(w, "Webhook recibido exitosamente")
}

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

	port := ":8080"
	log.Printf("Servidor de webhook iniciado en el puerto %s\n", port)
	log.Fatal(http.ListenAndServe(port, nil))
}

Este ejemplo básico configura un servidor HTTP que escucha en el puerto 8080 y maneja las solicitudes POST al endpoint /webhook. Lee la carga útil JSON entrante, la decodifica en una estructura WebhookPayload y registra el evento. Crucialmente, responde con un código de estado 200 OK para confirmar la recepción exitosa del webhook. No responder con un 200 OK puede hacer que el remitente reintente la entrega, lo que lleva a un procesamiento duplicado.

Garantizando la seguridad: Verificación de firma y HTTPS

La seguridad es primordial cuando se trata de datos sensibles de verificación de identidad. Debe asegurarse de que los webhooks entrantes sean legítimos y no hayan sido manipulados. Los dos mecanismos principales para esto son:

1. HTTPS: Siempre exponga su endpoint de webhook a través de HTTPS para cifrar los datos en tránsito, evitando la escucha.
2. Verificación de firma: La mayoría de los proveedores de verificación de identidad de buena reputación, incluido Didit, envían una firma o hash en los encabezados de la solicitud (por ejemplo, X-Didit-Signature). Debe usar una clave secreta compartida para calcular su propio hash del cuerpo de la solicitud sin procesar y compararlo con la firma entrante. Si no coinciden, es probable que el webhook sea fraudulento o esté comprometido.

Aquí hay un ejemplo de cómo podría agregar la verificación de firma a su controlador:

// ... (importaciones anteriores y estructura WebhookPayload)

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	// ... otras importaciones
)

const webhookSecret = "TU_SECRETO_WEBHOOK_DIDIT" // Reemplazar con tu secreto 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) {
	// ... (verificación de método y lectura del cuerpo)

	signature := r.Header.Get("X-Didit-Signature") // O nombre de encabezado similar de tu proveedor
	if signature == "" {
		http.Error(w, "Falta el encabezado de la firma", http.StatusUnauthorized)
		return
	}

	if !verifySignature(body, signature) {
		http.Error(w, "Firma inválida", http.StatusUnauthorized)
		return
	}

	// ... (deserialización y procesamiento de la carga útil)
}

Recuerde almacenar su webhookSecret de forma segura, idealmente en variables de entorno o un sistema de gestión de secretos, no codificado en su aplicación.

Robustez: Procesamiento asincrónico y reintentos

Los webhooks deben procesarse rápidamente para evitar tiempos de espera y reintentos por parte del remitente. Para tareas complejas o que requieren mucho tiempo, es mejor descargar el procesamiento a una goroutine o cola de mensajes separada. Su controlador de webhook debe centrarse principalmente en recibir, validar y reconocer el evento.

// ... (código anterior)

func processWebhookAsync(payload WebhookPayload) {
	// En una aplicación real, esto podría implicar:
	// - Almacenar el evento en una base de datos
	// - Enviar a una cola de mensajes (por ejemplo, Kafka, RabbitMQ)
	// - Llamar a otros servicios internos
	log.Printf("Procesando asincrónicamente el evento: %s para la sesión %s", payload.Event, payload.SessionID)
	// Simular trabajo
	// time.Sleep(5 * time.Second)
	log.Printf("Procesamiento asíncrono finalizado para la sesión %s", payload.SessionID)
}

func webhookHandler(w http.ResponseWriter, r *http.Request) {
	// ... (verificación de firma y deserialización de la carga útil)

	// Acuse de recibo inmediatamente.
	w.WriteHeader(http.StatusOK)
	fmt.Fprint(w, "Webhook recibido exitosamente")

	// Procesar asincrónicamente para evitar bloquear la respuesta HTTP.
	go processWebhookAsync(payload)
}

Además, los servicios externos pueden fallar ocasionalmente. Implemente mecanismos de reintento para cualquier llamada descendente realizada durante el procesamiento asincrónico. Considere usar una cola de mensajes fallidos (DLQ) para eventos que fallan repetidamente, lo que permite la inspección manual y el reprocesamiento.

Cómo Didit ayuda

Didit, como plataforma de identidad nativa de IA y centrada en el desarrollador, facilita y asegura la integración de eventos de verificación de identidad en tiempo real. La arquitectura modular de Didit está diseñada para la orquestación, lo que significa que puede definir flujos de trabajo complejos que combinan verificación de identificación (OCR, MRZ, códigos de barras), detección de vida pasiva y activa, coincidencia facial 1:1, detección y monitoreo AML, prueba de dirección e incluso estimación de edad que preserva la privacidad. Cada paso de estos flujos de trabajo, y el resultado final, puede activar eventos de webhook directamente a su aplicación Go.

Con Didit, configura su URL de webhook en la Consola Empresarial, y Didit envía actualizaciones automatizadas a su punto final configurado a medida que el usuario avanza y cuando el resultado final de la verificación está listo. Didit proporciona cargas útiles de webhook robustas, a menudo incluyendo un encabezado de firma para que usted verifique la autenticidad, asegurando la seguridad de su integración. Esto le permite construir respuestas sofisticadas y automatizadas a los resultados de la verificación, acelerando la incorporación de usuarios, mejorando la detección de fraude y optimizando los procesos de cumplimiento sin intervención manual.

Las ventajas de Didit, como el KYC Core gratuito y sin tarifas de configuración, junto con sus API limpias y documentación completa, le permiten construir soluciones de identidad potentes y basadas en eventos con la máxima eficiencia. Ya sea que utilice enlaces de verificación para una integración sin código o aproveche directamente la API, el sistema de webhook de Didit garantiza que siempre esté sincronizado con los viajes de verificación de sus usuarios.

¿Listo para comenzar?

¿Listo para ver Didit en acción? Obtenga una demostración gratuita hoy.

Comience a verificar identidades de forma gratuita con el nivel gratuito de Didit.