Вебхуки: подписанные payload'ы и повторные попытки для надёжных интеграций
Вы только что создали 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'ов
- Используйте надёжный секрет: Сгенерируйте случайный секрет длиной не менее 32 байт и храните его в безопасном месте (например, в переменной окружения или менеджере секретов).
- Включайте временную метку: Добавьте временную метку в подписанный payload и отклоняйте запросы старше нескольких минут, чтобы предотвратить атаки повторного воспроизведения.
- Используйте HTTPS: Всегда передавайте вебхуки через TLS, чтобы защитить payload и подпись при передаче.
- Периодически меняйте секреты: Поддерживайте несколько активных секретов во время ротации, чтобы избежать простоев.
Обработка сбоев: повторные попытки и идемпотентность
Вебхуки могут терпеть неудачу: ваш сервер может быть недоступен, сеть может разорваться, или ваш endpoint может вернуть ошибку. Надёжный отправитель будет повторять доставку, но вы должны спроектировать получатель так, чтобы он обрабатывал дубликаты и события, пришедшие не по порядку.
Стратегии повторных попыток
Большинство провайдеров вебхуков используют экспоненциальную задержку с джиттером. Например, повтор через 1 минуту, затем через 5 минут, затем через 30 минут, до максимального числа попыток. Это даёт вашей системе время на восстановление, не перегружая её.
Если вы создаёте сторону отправителя, реализуйте очередь с запланированными повторными попытками. Сохраняйте payload и количество попыток, а для обработки повторов используйте воркер.
Идемпотентность: ключ к безопасным повторным попыткам
Поскольку повторные попытки могут вызывать дублирующиеся доставки, ваш endpoint должен быть идемпотентным. Это означает, что обработка одного и того же события несколько раз должна иметь тот же эффект, что и однократная обработка.
Распространённые подходы:
- Используйте уникальный ID события: Включите ID в payload и сохраняйте обработанные ID в базе данных. Игнорируйте события с ID, которые вы уже видели.
- Проектируйте операции как идемпотентные: Например, используйте upsert вместо insert или проверяйте, существует ли ресурс, прежде чем создавать его.
Вот простая проверка идемпотентности на 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 мин) | Почти в реальном времени |
| Нагрузка на сервер | Постоянные запросы, даже когда нет изменений | Запросы только при событиях |
| Сложность | Простота реализации | Требует подписи, повторных попыток, идемпотентности |
| Надёжность | Вы контролируете повторные попытки | Зависит от политики повторных попыток отправителя |
Пошагово: реализация безопасного получателя вебхуков
- Настройте HTTPS endpoint, который принимает POST-запросы и читает исходное тело.
- Извлеките заголовок подписи (например,
X-Signature) и заголовок временной метки, если он присутствует. - Проверьте подпись с помощью HMAC и вашего секрета. Отклоните, если она недействительна.
- Проверьте временную метку, чтобы предотвратить атаки повторного воспроизведения (например, отклоните, если она старше 5 минут).
- Разберите payload и извлеките ID события.
- Проверьте идемпотентность, найдя ID события в вашей базе данных.
- Обработайте событие в рамках транзакции, которая также записывает ID события.
- Быстро верните статус 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-данные.