Вебхуки: подписанные данные и повторные попытки
Почему вебхуки ломаются в производственной среде
Вы создали конечную точку вебхука, протестировали её локально, и всё работает. Но в производственной среде возникают проблемы: провайдер отправляет дублирующее событие, ваша конечная точка не отвечает вовремя, или злоумышленник подделывает запрос. Внезапно ваша интеграция становится ненадежной и небезопасной.
Вебхуки просты по концепции — HTTP-обратные вызовы, инициируемые событиями, — но для производственных реализаций требуется тщательная проработка безопасности и надежности. Это руководство охватывает два критических аспекта: подписанные данные для проверки подлинности и стратегии повторных попыток для обработки сбоев.
Что такое вебхуки?
Вебхук — это определяемый пользователем HTTP-обратный вызов. Когда в исходной системе происходит событие (например, успешный платеж), она отправляет HTTP POST-запрос на указанный вами URL, содержащий данные о событии. Эта модель push-уведомлений эффективнее опроса.
Но вебхуки создают проблемы:
- Безопасность: Как узнать, что запрос пришел от законного отправителя?
- Надежность: Что, если ваша конечная точка недоступна или медленно отвечает?
- Дубликаты: Сеть может вызывать повторные попытки; вы можете получить одно и то же событие несколько раз.
Давайте сначала займемся безопасностью.
Защита вебхуков с помощью подписанных данных
Подписанные данные используют общий секрет для создания криптографической подписи тела запроса. Отправитель включает эту подпись в заголовок (например, X-Signature). Ваша конечная точка пересчитывает подпись и сравнивает её. Если они совпадают, запрос подлинный.
Как работает подпись HMAC
Большинство провайдеров используют HMAC-SHA256. Подпись вычисляется по исходному телу запроса с использованием общего секрета. Вот как это происходит:
- Провайдер и потребитель совместно используют секретный ключ.
- Провайдер создает полезную нагрузку, вычисляет HMAC-SHA256(секрет, полезная нагрузка) и отправляет её в заголовке.
- Потребитель получает запрос, читает исходное тело, вычисляет тот же HMAC и сравнивает.
Важно: Используйте исходное тело точно в том виде, в каком оно получено — парсинг и повторная сериализация JSON могут изменить байты и нарушить подпись.
Реализация проверки подписи
Вот пример на Node.js с использованием Express:
const crypto = require('crypto');
const express = require('express');
const app = express();
// Используйте парсер исходного тела для маршрутов вебхуков
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
const signature = req.headers['x-signature'];
const secret = process.env.WEBHOOK_SECRET;
const expected = crypto
.createHmac('sha256', secret)
.update(req.body)
.digest('hex');
if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
return res.status(401).send('Invalid signature');
}
// Обработка события
const event = JSON.parse(req.body);
// ... обработка события
res.status(200).send('OK');
});
Всегда используйте сравнение с постоянным временем, такое как crypto.timingSafeEqual, чтобы предотвратить атаки по времени.
Другие аспекты безопасности
- Проверка метки времени: Включите метку времени в подписанные данные и отклоняйте старые запросы, чтобы предотвратить атаки повторного воспроизведения.
- HTTPS: Всегда используйте HTTPS для конечных точек вебхуков.
- Ротация секретов: Поддерживайте несколько активных секретов, чтобы обеспечить ротацию без простоя.
Реализация надежных повторных попыток
Даже с защищенной конечной точкой сетевые проблемы или временные сбои могут привести к неудачной доставке вебхука. Надежный механизм повторных попыток гарантирует, что события не будут потеряны.
Стратегия повторных попыток на стороне отправителя
Если вы создаете отправителя вебхуков, реализуйте экспоненциальную задержку с джиттером. Например:
- Повтор 1: через 1 минуту
- Повтор 2: через 5 минут
- Повтор 3: через 30 минут
- Повтор 4: через 2 часа
- Повтор 5: через 24 часа
Добавьте случайный джиттер, чтобы избежать проблемы «стада». Остановитесь после максимального числа попыток и отправьте уведомление.
Лучшие практики на стороне получателя
Как потребитель вебхуков, вы не можете контролировать политику повторных попыток отправителя, но можете сделать свою конечную точку устойчивой:
- Отвечайте быстро: Подтвердите получение статусом 2xx перед выполнением тяжелой работы. Используйте очередь.
- Идемпотентность: Обрабатывайте дублирующиеся события корректно. Используйте ID события для дедупликации.
- Мониторинг сбоев: Регистрируйте сбои и настройте оповещения.
Обработка дубликатов с помощью идемпотентности
Провайдеры вебхуков часто повторяют попытки при тайм-аутах, поэтому вы можете получить одно и то же событие несколько раз. Сделайте обработку идемпотентной:
- Сохраняйте ID обработанных событий в базе данных с уникальным ограничением.
- Перед обработкой проверьте, существует ли уже ID; если да, верните 200 OK без повторной обработки.
- Для операций, изменяющих состояние, используйте ключи идемпотентности.
Пример с использованием уникального индекса базы данных:
async function handleEvent(event) {
try {
await db.query('INSERT INTO processed_events (id) VALUES ($1)', [event.id]);
} catch (err) {
if (err.code === '23505') { // нарушение уникальности
return; // уже обработано
}
throw err;
}
// обработка события
}
Сравнение: подходы к безопасности вебхуков
| Подход | Плюсы | Минусы |
|---|---|---|
| Подпись HMAC | Строгая целостность, широко поддерживается | Требует управления секретами |
| Basic Auth | Простота | Менее безопасно, учетные данные в заголовке |
| Белый список IP | Легко реализовать | IP могут меняться, не надежно |
Подписи HMAC являются де-факто стандартом безопасности вебхуков.
Тестирование вебхуков локально
Инструменты вроде ngrok или localtunnel открывают ваш локальный сервер в интернет для тестирования. Всегда тестируйте проверку подписи и логику повторных попыток с имитацией сбоев.
При проверке JSON-полезных нагрузок от вебхуков форматирование может помочь в отладке. Попробуйте наш JSON Formatter для красивого вывода и валидации полезных нагрузок вебхуков.
Часто задаваемые вопросы
Как проверить подпись вебхука?
Вычислите HMAC исходного тела запроса с использованием общего секрета, затем сравните его с заголовком подписи, используя функцию сравнения с постоянным временем.
Что делать, если моя конечная точка вебхука недоступна?
Большинство провайдеров повторяют попытки с экспоненциальной задержкой. Убедитесь, что ваша конечная точка быстро возвращает 2xx и обрабатывает асинхронно, чтобы минимизировать влияние простоя.
Можно ли использовать вебхуки без подписей?
Это рискованно. Без подписей злоумышленники могут подделывать запросы. Всегда используйте подписанные данные или, по крайней мере, базовую аутентификацию через HTTPS.
Заключение
Вебхуки мощны, но требуют внимания к безопасности и надежности. Реализуйте проверку подписи HMAC для обеспечения подлинности и проектируйте систему для корректной обработки повторных попыток и дубликатов. С этими практиками ваши интеграции вебхуков будут надежными и готовыми к производственной среде.