Вебхуки: подписанные данные и надёжные повторы
Вы только что интегрировали сторонний сервис, который отправляет вебхуки на ваш эндпоинт. Всё работает в тестах, но в продакшене вы замечаете пропущенные события, дублирующиеся доставки и даже поддельные запросы. Вебхуки просты в концепции, но их сложно реализовать правильно. В этой статье объясняется, как защитить вебхуки с помощью подписанных данных и реализовать надёжную логику повторных попыток, чтобы ваши интеграции были устойчивыми и заслуживающими доверия.
Что такое вебхуки и почему они важны
Вебхуки — это определяемые пользователем HTTP-обратные вызовы, инициируемые событиями. Вместо опроса API на предмет изменений вы регистрируете URL, и сервис отправляет POST-запрос с данными события всякий раз, когда что-то происходит. Эта модель push снижает задержку и нагрузку на сервер, что делает её идеальной для интеграций в реальном времени, таких как уведомления о платежах, триггеры CI/CD и сообщения в чатах.
Однако вебхуки создают проблемы: проверка подлинности, обработка сбоев и обеспечение однократной обработки. Давайте разберём их по порядку.
Защита вебхуков с помощью подписанных данных
Без проверки любой может отправить поддельные запросы на ваш эндпоинт вебхука. Подписанные данные решают эту проблему, включая криптографическую подпись в заголовках запроса, сгенерированную с использованием общего секрета. Вы проверяете подпись, чтобы подтвердить, что запрос пришёл от ожидаемого отправителя и не был изменён.
Как работают подписи HMAC
Большинство сервисов используют HMAC (код аутентификации сообщений на основе хэша) с SHA-256. Отправитель вычисляет хэш тела запроса (а иногда и временной метки) с использованием секрета и включает его в заголовок, например X-Signature. Вы пересчитываете хэш на своей стороне и сравниваете.
Вот типичный процесс проверки в Node.js:
const crypto = require('crypto');
function verifySignature(payload, signature, secret) {
const expected = crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expected)
);
}
Всегда используйте сравнение, устойчивое к атакам по времени, чтобы предотвратить временные атаки. Также включайте временную метку в подписанные данные и отклоняйте запросы старше нескольких минут, чтобы предотвратить атаки повторного воспроизведения.
Лучшие практики проверки подписи
- Используйте HTTPS для защиты данных при передаче.
- Храните секреты безопасно (например, переменные окружения, менеджеры секретов).
- Проверяйте временную метку и отклоняйте устаревшие запросы.
- Регистрируйте сбои проверки для мониторинга.
Реализация надёжных повторных попыток
Сети дают сбои, серверы перезагружаются, а эндпоинты работают с тайм-аутом. Надёжная система вебхуков должна повторять неудачные доставки. Но повторные попытки могут вызывать дубликаты, поэтому вам нужна идемпотентность.
Стратегии повторных попыток
Большинство провайдеров используют экспоненциальную задержку с джиттером. Например, повтор через 1 минуту, затем через 5 минут, затем через 30 минут, до максимального числа попыток (например, 5). Включайте уникальный ID события в данные, чтобы получатель мог выполнить дедупликацию.
На принимающей стороне быстро отвечайте статусом 2xx, чтобы подтвердить получение, а затем обрабатывайте асинхронно. Если обработка не удалась, вы не можете полагаться на то, что отправитель будет повторять бесконечно — реализуйте свою собственную очередь недоставленных сообщений или оповещения.
Ключи идемпотентности
Для обработки дублирующихся доставок используйте ключ идемпотентности (часто это ID события) и сохраняйте обработанные ID на разумный период. Перед обработкой проверьте, не встречался ли уже этот ID; если да, верните успех без повторной обработки.
// Пример: проверка идемпотентности в Express
app.post('/webhook', async (req, res) => {
const eventId = req.body.id;
if (await db.seenEvents.has(eventId)) {
return res.status(200).send('Already processed');
}
await db.seenEvents.add(eventId);
// process event asynchronously
res.status(200).send('OK');
});
Сравнение: опрос vs вебхуки
| Аспект | Опрос | Вебхуки |
|---|---|---|
| Задержка | Высокая (на основе интервала) | Низкая (почти в реальном времени) |
| Нагрузка на сервер | Высокая (частые запросы) | Низкая (управляемая событиями) |
| Сложность | Простота реализации | Требуется проверка подписи и повторные попытки |
| Надёжность | Зависит от частоты опроса | Зависит от механизма повторных попыток |
Пошагово: создание безопасного получателя вебхуков
- Настройте эндпоинт, который принимает POST-запросы по HTTPS.
- Проверьте подпись с использованием общего секрета и отклоняйте недействительные запросы с кодом 401.
- Проверьте временную метку, чтобы предотвратить атаки повторного воспроизведения.
- Отвечайте немедленно с кодом 200 OK после базовой проверки, затем обрабатывайте асинхронно.
- Реализуйте идемпотентность с использованием ID событий, чтобы избежать повторной обработки.
- Регистрируйте и отслеживайте сбои и повторные попытки.
Часто задаваемые вопросы
Что такое подписанные данные вебхука?
Подписанные данные включают криптографическую подпись (обычно HMAC), которая позволяет получателю проверить подлинность и целостность запроса с использованием общего секрета.
Сколько раз следует повторять неудачный вебхук?
Обычная практика — 3–5 повторных попыток с экспоненциальной задержкой. После этого переместите событие в очередь недоставленных сообщений для ручной проверки.
Можно ли использовать вебхуки без HTTPS?
Нет, HTTPS необходим для защиты данных и подписи от перехвата и подделки. Всегда используйте TLS.
Готовы протестировать свои данные вебхуков? Используйте наш JSON-форматтер, чтобы быстро отформатировать и проверить JSON-данные.