Вебхуки: подписанные данные и повторные попытки
Вы только что интегрировали платежного провайдера или сервис CI/CD, и теперь вам нужно получать события в реальном времени. Вебхуки — это стандартный способ передачи данных между системами, но многие реализации терпят неудачу в продакшене из-за уязвимостей безопасности или ненадежной доставки. В этом руководстве объясняется, как защитить вебхуки с помощью подписанных данных и реализовать надежные механизмы повторных попыток.
Что такое вебхуки и почему они важны
Вебхук — это HTTP-колбэк: когда в исходной системе происходит событие (например, новый заказ), она отправляет HTTP POST-запрос на указанный вами URL. В отличие от опроса (polling), вебхуки эффективны и работают почти в реальном времени. Однако, поскольку они основаны на HTTP, вы должны явно обеспечить безопасность и надежность.
Типичные случаи использования включают уведомления о платежах, триггеры пайплайнов CI/CD, уведомления в чатах и синхронизацию данных между SaaS-приложениями.
Защита вебхуков с помощью подписанных данных
Вебхуки — это общедоступные эндпоинты, поэтому злоумышленники могут отправлять поддельные запросы. Чтобы предотвратить это, провайдеры подписывают каждый payload секретным ключом. Получатель проверяет подпись, чтобы убедиться в подлинности и целостности.
Как работают подписи HMAC
Наиболее распространенный метод — HMAC-SHA256. Провайдер вычисляет хеш тела запроса с использованием общего секрета и включает его в заголовок (например, X-Signature). Получатель пересчитывает хеш и сравнивает его.
// Пример на Node.js: генерация подписи
const crypto = require('crypto');
const secret = 'your_webhook_secret';
const payload = JSON.stringify({ event: 'order.created', id: 123 });
const signature = crypto.createHmac('sha256', secret).update(payload).digest('hex');
// Отправьте подпись в заголовке: X-Signature: sha256=...
Проверка подписей на получателе
Всегда используйте сравнение с постоянным временем, чтобы предотвратить атаки по времени. В Node.js используйте crypto.timingSafeEqual.
// Пример middleware для Express.js
const crypto = require('crypto');
function verifySignature(req, res, next) {
const signature = req.headers['x-signature'];
const payload = JSON.stringify(req.body); // требуется сырое тело
const expected = crypto.createHmac('sha256', secret).update(payload).digest('hex');
const trusted = Buffer.from(`sha256=${expected}`, 'utf8');
const received = Buffer.from(signature, 'utf8');
if (trusted.length !== received.length || !crypto.timingSafeEqual(trusted, received)) {
return res.status(401).send('Invalid signature');
}
next();
}
Важно: Используйте для проверки сырое тело запроса, а не распарсенный JSON, чтобы избежать расхождений.
Дополнительные меры безопасности
- Проверка временной метки: Включите временную метку в подпись и отклоняйте запросы старше нескольких минут, чтобы предотвратить повторные атаки.
- Только HTTPS: Всегда используйте HTTPS-эндпоинты для защиты данных при передаче.
- Белый список IP: Если провайдер публикует диапазоны IP, ограничьте входящие запросы этими IP.
Реализация надежных повторных попыток
Вебхуки могут завершаться неудачно из-за проблем с сетью, простоя сервера или ошибок. Провайдеры обычно повторяют неудачные доставки с экспоненциальной задержкой. Как получатель, вы должны быть идемпотентными и обрабатывать дублирующиеся события.
Проектирование с учетом идемпотентности
Каждое событие вебхука должно иметь уникальный ID. Сохраняйте обработанные ID, чтобы игнорировать дубликаты. Используйте базу данных с уникальным ограничением или кэш, например Redis.
// Псевдокод для идемпотентной обработки
if (await redis.exists(`webhook:${event.id}`)) {
return res.status(200).send('Already processed');
}
await processEvent(event);
await redis.set(`webhook:${event.id}`, '1', 'EX', 86400); // 24h TTL
Стратегии повторных попыток
Провайдеры обычно повторяют попытки с увеличивающимися задержками (например, 1с, 5с, 30с, 5м, 1ч). Убедитесь, что ваш эндпоинт отвечает быстро (в течение 5 секунд), чтобы избежать таймаутов. Если обработка занимает больше времени, подтвердите получение и обработайте асинхронно.
Вот сравнение распространенных шаблонов повторных попыток:
| Шаблон | Плюсы | Минусы |
|---|---|---|
| Фиксированный интервал | Простота | Может нагрузить восстанавливающийся сервер |
| Экспоненциальная задержка | Снижает нагрузку во время сбоев | Задержка доставки при временных ошибках |
| Экспоненциальная задержка с джиттером | Предотвращает эффект «стада» | Немного сложнее |
Мониторинг и очереди недоставленных сообщений
Регистрируйте все попытки и сбои вебхуков. После максимального числа повторных попыток перемещайте события в очередь недоставленных сообщений (DLQ) для ручной проверки. Настройте оповещения о высоком уровне сбоев.
Собираем все вместе: пошаговая реализация
- Настройте HTTPS-эндпоинт, который принимает POST-запросы и читает сырое тело.
- Проверьте подпись с использованием общего секрета и сравнения с постоянным временем.
- Проверьте временную метку, чтобы предотвратить повторные атаки (если она предоставлена).
- Обеспечьте идемпотентность, проверяя ID события по кэшу или базе данных.
- Обрабатывайте событие асинхронно, если это может занять время; немедленно отвечайте 200 OK.
- Реализуйте логику повторных попыток на стороне отправителя с экспоненциальной задержкой и джиттером.
- Мониторинг и оповещения о сбоях, а также используйте DLQ для постоянных ошибок.
Часто задаваемые вопросы
Что такое подписанный payload вебхука?
Подписанный payload включает криптографическую подпись (обычно HMAC), которая позволяет получателю проверить, что запрос пришел из доверенного источника и не был изменен.
Как обрабатывать дублирующиеся события вебхуков?
Используйте уникальный ID события, предоставленный в payload, для отслеживания обработанных событий. Сохраняйте ID в базе данных или кэше с TTL, чтобы игнорировать дубликаты.
Что должен возвращать мой эндпоинт вебхука?
Быстро возвращайте код состояния 2xx (например, 200 OK), чтобы подтвердить получение. Если обработка не удалась, верните 5xx, чтобы инициировать повторную попытку, но только для временных ошибок.
При тестировании payload вебхуков вам может потребоваться проверить структуры JSON. Используйте JSON Formatter, чтобы проверять и форматировать payload вебхуков для упрощения отладки.