Создание обработчика веб-хуков Go для событий верификации личности (RU)

Автоматизация в реальном времениВеб-хуки обеспечивают мгновенные, управляемые событиями ответы на результаты верификации личности, что критически важно для динамической регистрации пользователей и систем предотвращения мошенничества.

Надёжная обработка ошибокВнедрение механизмов повторных попыток, очередей "мёртвых писем" и всестороннего логирования жизненно важно для поддержания целостности данных и надёжности системы при обработке асинхронных событий веб-хуков.

Безопасность превыше всегоВсегда проверяйте подписи веб-хуков, используйте HTTPS и очищайте входящие данные для защиты от подделки и несанкционированного доступа, обеспечивая безопасность конфиденциальной информации о личности.

Didit упрощает интеграциюМодульная, API-ориентированная платформа Didit обеспечивает всестороннюю поддержку веб-хуков, позволяя разработчикам легко настраивать уведомления в реальном времени для всех событий верификации личности, от проверки ID до AML-скрининга, с бесплатным базовым KYC.

В современном мире цифровой идентификации обратная связь в реальном времени — это не просто роскошь; это необходимость. Независимо от того, регистрируете ли вы новых пользователей, предотвращаете мошенничество или обеспечиваете соответствие требованиям, знание результата проверки личности в момент её возникновения позволяет немедленно принять меры и обеспечить более плавный пользовательский опыт. Именно здесь веб-хуки проявляют себя наилучшим образом. Веб-хуки предоставляют мощный механизм для платформ верификации личности, чтобы уведомлять ваше приложение о событиях по мере их возникновения, устраняя необходимость в постоянном опросе.

Эта статья проведёт вас через создание надёжного и безопасного обработчика веб-хуков на Go, специально предназначенного для обработки событий верификации личности. Мощные функции параллелизма и производительность Go делают его отличным выбором для обработки асинхронной природы веб-хуков.

Понимание веб-хуков для верификации личности

Прежде чем углубляться в код, давайте проясним, что такое веб-хуки и почему они критически важны для верификации личности. Веб-хук — это, по сути, определённый пользователем HTTP-колбэк. Вместо того чтобы ваше приложение постоянно запрашивало обновления у службы верификации личности (опрос), служба отправляет HTTP POST-запрос на указанный вами URL всякий раз, когда происходит определённое событие. Для верификации личности эти события могут включать:

• Сканирование документа, удостоверяющего личность пользователя, завершено.
• Проверка живости пройдена или не пройдена.
• AML-скрининг выявил совпадение.
• Полный рабочий процесс верификации достиг окончательного статуса (например, одобрено, отклонено, ручной просмотр).

Получение этих событий в реальном времени позволяет вашему приложению обновлять статусы пользователей, запускать последующие процессы или уведомлять администраторов без задержек. Например, как только проверка ID пользователя и пассивная/активная проверка живости будут одобрены, вы можете немедленно предоставить ему доступ к вашему сервису.

Настройка вашего Go веб-хук сервера

Создание обработчика веб-хуков на Go включает настройку простого HTTP-сервера, который прослушивает входящие POST-запросы. Мы будем использовать стандартный пакет Go net/http для этого. Сначала давайте создадим базовую структуру сервера.

package main

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

// WebhookPayload представляет структуру входящего веб-хука от службы верификации личности.
// Это упрощённый пример; фактические данные будут различаться.
type WebhookPayload struct {
	Event   string `json:"event"`
	SessionID string `json:"session_id"`
	Status  string `json:"status"`
	Data    json.RawMessage `json:"data"` // Используйте RawMessage для отложенной демаршализации вложенных данных
}

func webhookHandler(w http.ResponseWriter, r *http.Request) {
	if r.Method != http.MethodPost {
		http.Error(w, "Метод не разрешён", http.StatusMethodNotAllowed)
		return
	}

	body, err := ioutil.ReadAll(r.Body)
	if err != nil {
		http.Error(w, "Ошибка чтения тела запроса", http.StatusInternalServerError)
		return
	}

	var payload WebhookPayload
	err = json.Unmarshal(body, &payload)
	if err != nil {
		http.Error(w, "Ошибка демаршализации JSON-данных", http.StatusBadRequest)
		log.Printf("Не удалось демаршализировать веб-хук: %v, Тело: %s", err, body)
		return
	}

	// Пока просто логируем полученное событие. В реальном приложении вы бы его обрабатывали.
	log.Printf("Получено событие веб-хука: %s для сессии %s со статусом %s", payload.Event, payload.SessionID, payload.Status)

	// Отвечаем 200 OK для подтверждения получения. Большинство отправителей веб-хуков ожидают этого.
	w.WriteHeader(http.StatusOK)
	fmt.Fprint(w, "Веб-хук успешно получен")
}

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

	port := ":8080"
	log.Printf("Сервер веб-хуков запускается на порту %s\n", port)
	log.Fatal(http.ListenAndServe(port, nil))
}

Этот базовый пример настраивает HTTP-сервер, прослушивающий порт 8080 и обрабатывающий POST-запросы к конечной точке /webhook. Он читает входящий JSON-загрузку, демаршализирует её в структуру WebhookPayload и логирует событие. Что крайне важно, он отвечает статусом 200 OK, чтобы подтвердить успешное получение веб-хука. Отсутствие ответа со статусом 200 OK может привести к повторной попытке доставки со стороны отправителя, что приведёт к дублированию обработки.

Обеспечение безопасности: проверка подписи и HTTPS

Безопасность является первостепенной при работе с конфиденциальными данными верификации личности. Вы должны убедиться, что входящие веб-хуки являются законными и не были подделаны. Двумя основными механизмами для этого являются:

1. HTTPS: Всегда открывайте конечную точку веб-хука через HTTPS для шифрования данных при передаче, предотвращая перехват.
2. Проверка подписи: Большинство авторитетных поставщиков услуг верификации личности, включая Didit, отправляют подпись или хеш в заголовках запроса (например, X-Didit-Signature). Вы должны использовать общий секретный ключ для вычисления собственного хеша необработанного тела запроса и сравнения его с входящей подписью. Если они не совпадают, веб-хук, вероятно, является мошенническим или скомпрометированным.

Вот пример того, как вы можете добавить проверку подписи к вашему обработчику:

// ... (предыдущие импорты и структура WebhookPayload)

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	// ... другие импорты
)

const webhookSecret = "YOUR_DIDIT_WEBHOOK_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) {
	// ... (проверка метода и чтение тела)

	signature := r.Header.Get("X-Didit-Signature") // Или аналогичное имя заголовка от вашего провайдера
	if signature == "" {
		http.Error(w, "Отсутствует заголовок подписи", http.StatusUnauthorized)
		return
	}

	if !verifySignature(body, signature) {
		http.Error(w, "Недействительная подпись", http.StatusUnauthorized)
		return
	}

	// ... (демаршализация и обработка полезной нагрузки)
}

Не забудьте безопасно хранить ваш webhookSecret, в идеале в переменных окружения или системе управления секретами, а не жёстко прописывать в вашем приложении.

Надёжность: асинхронная обработка и повторные попытки

Веб-хуки должны обрабатываться быстро, чтобы избежать тайм-аутов и повторных попыток со стороны отправителя. Для сложных или трудоёмких задач лучше передать обработку отдельной горутине или очереди сообщений. Ваш обработчик веб-хуков должен в первую очередь сосредоточиться на получении, проверке и подтверждении события.

// ... (предыдущий код)

func processWebhookAsync(payload WebhookPayload) {
	// В реальном приложении это может включать:
	// - Хранение события в базе данных
	// - Отправку в очередь сообщений (например, Kafka, RabbitMQ)
	// - Вызов других внутренних сервисов
	log.Printf("Асинхронная обработка события: %s для сессии %s", payload.Event, payload.SessionID)
	// Имитация работы
	// time.Sleep(5 * time.Second)
	log.Printf("Завершена асинхронная обработка для сессии %s", payload.SessionID)
}

func webhookHandler(w http.ResponseWriter, r *http.Request) {
	// ... (проверка подписи и демаршализация полезной нагрузки)

	// Немедленно подтверждаем получение.
	w.WriteHeader(http.StatusOK)
	fmt.Fprint(w, "Веб-хук успешно получен")

	// Обрабатываем асинхронно, чтобы не блокировать HTTP-ответ.
	go processWebhookAsync(payload)
}

Кроме того, внешние сервисы иногда могут давать сбои. Реализуйте механизмы повторных попыток для любых последующих вызовов, сделанных во время асинхронной обработки. Рассмотрите возможность использования очереди "мёртвых писем" (DLQ) для событий, которые неоднократно завершаются сбоем, что позволит вручную проверять и повторно обрабатывать их.

Как Didit помогает

Didit, как AI-ориентированная платформа идентификации, ориентированная на разработчиков, делает интеграцию событий верификации личности в реальном времени простой и безопасной. Модульная архитектура Didit создана для оркестрации, что означает, что вы можете определять сложные рабочие процессы, объединяющие верификацию ID (OCR, MRZ, штрих-коды), пассивную и активную проверку живости, сопоставление лиц 1:1, AML-скрининг и мониторинг, подтверждение адреса и даже оценку возраста с сохранением конфиденциальности. Каждый шаг этих рабочих процессов и конечный результат могут запускать события веб-хуков непосредственно в ваше приложение Go.

С Didit вы настраиваете свой URL веб-хука в Business Console, и Didit отправляет автоматические обновления на вашу настроенную конечную точку по мере продвижения пользователя и когда окончательный результат верификации готов. Didit предоставляет надёжные полезные нагрузки веб-хуков, часто включая заголовок подписи для проверки подлинности, обеспечивая безопасность вашей интеграции. Это позволяет создавать сложные, автоматизированные ответы на результаты верификации, ускоряя регистрацию пользователей, улучшая обнаружение мошенничества и оптимизируя процессы соответствия без ручного вмешательства.

Преимущества Didit, такие как бесплатный базовый KYC и отсутствие платы за настройку, в сочетании с его чистыми API и всеобъемлющей документацией, позволяют создавать мощные, управляемые событиями решения для идентификации с максимальной эффективностью. Независимо от того, используете ли вы ссылки для верификации для интеграции без кода или напрямую используете API, система веб-хуков Didit гарантирует, что вы всегда будете в курсе процессов верификации ваших пользователей.

Готовы начать?

Хотите увидеть Didit в действии? Получите бесплатную демонстрацию сегодня.

Начните бесплатно верифицировать личности с бесплатным тарифом Didit.