Вебхуки: подписанные данные и стратегии повторных попыток

Backend2026-11-12TryQuickToolBox

Вы создали API, который отправляет вебхуки для уведомления внешних сервисов о событиях. Но что происходит, когда принимающая конечная точка недоступна? Или когда злоумышленник пытается подделать запрос вебхука? Без надлежащих мер защиты ваши вебхуки могут стать источником несоответствия данных и уязвимостей безопасности. В этой статье объясняется, как реализовать подписанные данные и механизмы повторных попыток, чтобы сделать ваши вебхуки надёжными и безопасными.

Что такое вебхуки и почему им нужна безопасность?

Вебхуки — это определяемые пользователем HTTP-обратные вызовы, которые запускаются определёнными событиями. Они обеспечивают связь в реальном времени между системами, например, уведомление платёжного сервиса при размещении заказа. Однако, поскольку вебхуки являются общедоступными конечными точками, они подвержены подделке и атакам повторного воспроизведения. Кроме того, проблемы с сетью или простои получателя могут привести к пропуску событий. Следовательно, необходимо решить два критических аспекта: подлинность (через подписанные данные) и надёжность (через повторные попытки).

Подписанные данные: обеспечение подлинности и целостности

Подписанные данные позволяют получателю проверить, что вебхук исходит из доверенного источника и что данные не были изменены. Обычно это достигается с помощью HMAC (код аутентификации сообщений на основе хэша) с общим секретом.

Как работает подпись HMAC

Отправитель и получатель совместно используют секретный ключ. Для каждого запроса вебхука отправитель вычисляет подпись HMAC, используя секрет и полезную нагрузку запроса (часто включая временную метку для предотвращения атак повторного воспроизведения). Подпись отправляется в заголовке, например, X-Signature. Получатель пересчитывает подпись и сравнивает её с полученной. Если они совпадают, запрос является подлинным.

Вот пример на Python с использованием HMAC-SHA256:

import hmac
import hashlib
import time

secret = b'your_shared_secret'
payload = b'{"event":"order.created","id":123}'
timestamp = str(int(time.time())).encode()
message = timestamp + b'.' + payload
signature = hmac.new(secret, message, hashlib.sha256).hexdigest()

# Отправьте заголовки: X-Signature: signature, X-Timestamp: timestamp

На стороне получателя проверьте подпись и временную метку, чтобы убедиться, что запрос является свежим (например, в пределах 5 минут). Это предотвращает атаки повторного воспроизведения.

Лучшие практики для подписанных данных

Механизмы повторных попыток: обеспечение надёжной доставки

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

Разработка политики повторных попыток

Распространённый подход — экспоненциальная задержка с джиттером. Например, повторная попытка через 1 минуту, затем через 5 минут, затем через 30 минут, до максимального количества попыток (например, 5). Включите уникальный идентификатор события в полезную нагрузку, чтобы получатель мог выполнить дедупликацию.

Пример расписания повторных попыток:

ПопыткаЗадержка
1Немедленно
21 минута
35 минут
430 минут
52 часа

После исчерпания повторных попыток переместите событие в очередь недоставленных сообщений для ручной проверки.

Идемпотентность: обработка дублирующихся доставок

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

Реализация вебхуков: пошаговое руководство

  1. Определите события и структуру полезной нагрузки: Документируйте события, которые генерирует ваша система, и JSON-схему для каждого.
  2. Сгенерируйте секрет: Создайте уникальный секрет для каждой конечной точки вебхука и передайте его безопасным способом.
  3. Подписывайте каждый запрос: Вычисляйте HMAC для полезной нагрузки и временной метки, включайте в заголовки.
  4. Реализуйте повторные попытки с задержкой: Используйте систему очередей для планирования повторных попыток.
  5. Предоставьте способ проверки подписей: Документируйте процесс проверки для получателей.
  6. Мониторинг и журналирование: Отслеживайте попытки доставки и сбои для отладки.

Распространённые ошибки и как их избежать

Часто задаваемые вопросы

Что такое подписанная полезная нагрузка вебхука?

Подписанная полезная нагрузка вебхука включает криптографическую подпись (например, HMAC), которая позволяет получателю проверить подлинность отправителя и целостность данных.

Сколько раз следует повторять неудачный вебхук?

Обычно от 3 до 5 повторных попыток с экспоненциальной задержкой. Точное число зависит от вашего SLA и критичности события.

Можно ли использовать JWT вместо HMAC для подписей вебхуков?

Да, JWT можно использовать, но HMAC проще и более распространён для подписи вебхуков. JWT добавляет накладные расходы и лучше подходит для токенов аутентификации.

Готовы протестировать полезные нагрузки вебхуков? Используйте наш JSON-форматтер для проверки и форматирования ваших JSON-полезных нагрузок перед отправкой.