Вебхуки: подписанные payload'ы и повторные попытки для надёжных интеграций

Backend2026-11-13TryQuickToolBox

Вы только что создали endpoint для получения вебхуков от платёжного провайдера. Первый тест проходит успешно, но в production вы замечаете пропущенные события, дублирующиеся списания и отсутствие способа определить, является ли запрос подлинным. Вебхуки просты в концепции, но их правильная реализация требует внимания. Это руководство объясняет, как защитить вебхуки с помощью подписанных payload'ов и реализовать надёжную логику повторных попыток, чтобы ваши интеграции не ломались молча.

Что такое вебхуки и почему они важны

Вебхуки — это определяемые пользователем HTTP-колбэки, запускаемые событиями. Вместо того чтобы ваше приложение опрашивало API на предмет изменений, сервис отправляет данные на ваш endpoint, когда что-то происходит. Это делает интеграции эффективными и почти в реальном времени.

Типичные случаи использования включают уведомления о платежах (например, Stripe), триггеры CI/CD (например, GitHub) и платформы обмена сообщениями (например, Slack). Но при такой модели push вы теряете контроль над тем, когда приходят запросы. Поэтому необходимо явно обрабатывать безопасность и надёжность.

Проблема безопасности: неподписанные вебхуки опасны

Неподписанный вебхук — это просто HTTP POST на публичный URL. Любой может отправить запрос, который выглядит так, будто он пришёл от вашего платёжного провайдера. Без проверки злоумышленники могут подделать события, что приведёт к мошенническим заказам, утечкам данных или несанкционированным действиям.

Решение — подписывать payload. Отправитель вычисляет криптографическую подпись для тела запроса, используя общий секрет, и включает её в заголовок. Ваш endpoint пересчитывает подпись и сравнивает её. Если они совпадают, вы знаете, что запрос подлинный и не был изменён.

Как подписывать payload'ы вебхуков с помощью HMAC

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

Вот как отправитель может подписать payload на Python:

import hmac
import hashlib
import json

secret = b'your_shared_secret'
payload = json.dumps({'event': 'payment.success', 'amount': 1000}).encode('utf-8')
signature = hmac.new(secret, payload, hashlib.sha256).hexdigest()
# Include signature in header: X-Signature: 

На принимающей стороне вы должны проверить подпись перед обработкой payload:

import hmac
import hashlib

def verify_signature(payload, received_signature, secret):
    expected = hmac.new(secret, payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, received_signature)

Важно: Всегда используйте функцию сравнения с постоянным временем, такую как hmac.compare_digest, чтобы предотвратить атаки по времени. Также проверяйте подпись по исходному телу запроса, а не по его разобранной версии, потому что сериализация JSON может отличаться.

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

Обработка сбоев: повторные попытки и идемпотентность

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

Стратегии повторных попыток

Большинство провайдеров вебхуков используют экспоненциальную задержку с джиттером. Например, повтор через 1 минуту, затем через 5 минут, затем через 30 минут, до максимального числа попыток. Это даёт вашей системе время на восстановление, не перегружая её.

Если вы создаёте сторону отправителя, реализуйте очередь с запланированными повторными попытками. Сохраняйте payload и количество попыток, а для обработки повторов используйте воркер.

Идемпотентность: ключ к безопасным повторным попыткам

Поскольку повторные попытки могут вызывать дублирующиеся доставки, ваш endpoint должен быть идемпотентным. Это означает, что обработка одного и того же события несколько раз должна иметь тот же эффект, что и однократная обработка.

Распространённые подходы:

Вот простая проверка идемпотентности на Python:

def process_event(event_id, payload):
    if db.exists('processed_events', event_id):
        return  # already processed
    # process payload
    db.insert('processed_events', event_id)

Убедитесь, что проверка и обработка происходят в одной транзакции, чтобы избежать состояний гонки.

Сравнение: опрос vs. вебхуки

АспектОпросВебхуки
ЗадержкаЗависит от интервала (например, 5 мин)Почти в реальном времени
Нагрузка на серверПостоянные запросы, даже когда нет измененийЗапросы только при событиях
СложностьПростота реализацииТребует подписи, повторных попыток, идемпотентности
НадёжностьВы контролируете повторные попыткиЗависит от политики повторных попыток отправителя

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

  1. Настройте HTTPS endpoint, который принимает POST-запросы и читает исходное тело.
  2. Извлеките заголовок подписи (например, X-Signature) и заголовок временной метки, если он присутствует.
  3. Проверьте подпись с помощью HMAC и вашего секрета. Отклоните, если она недействительна.
  4. Проверьте временную метку, чтобы предотвратить атаки повторного воспроизведения (например, отклоните, если она старше 5 минут).
  5. Разберите payload и извлеките ID события.
  6. Проверьте идемпотентность, найдя ID события в вашей базе данных.
  7. Обработайте событие в рамках транзакции, которая также записывает ID события.
  8. Быстро верните статус 2xx, чтобы подтвердить получение. Если обработка занимает время, поставьте задачу в очередь и верните 202 Accepted.

Тестирование вашей реализации вебхуков

Используйте такие инструменты, как ngrok, чтобы открыть доступ к вашему локальному серверу и имитировать вебхуки. Напишите модульные тесты для проверки подписи, идемпотентности и логики повторных попыток. Например, проверьте, что дублирующийся ID события игнорируется, а недействительная подпись возвращает 401.

При отладке логируйте полученный payload и подпись (но никогда не логируйте секреты). Если вы работаете с JSON payload'ами, JSON formatter может помочь вам быстро проверить и валидировать структуру.

FAQ

Что такое подписанный payload вебхука?

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

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

Универсального числа нет, но распространённая практика — 3–5 повторных попыток с экспоненциальной задержкой. После этого событие часто помечается как неудачное и может потребовать ручного вмешательства или очереди недоставленных сообщений.

Можно ли использовать вебхуки без HTTPS?

Никогда не используйте вебхуки по обычному HTTP. Без TLS злоумышленники могут перехватить payload и подпись, а также воспроизвести или изменить запросы. Всегда используйте HTTPS.

Готовы проверять и форматировать payload'ы вебхуков? Попробуйте наш бесплатный JSON formatter, чтобы мгновенно валидировать и форматировать JSON-данные.