Вебхуки: подписанные данные и надёжные повторы

Backend2026-11-17TryQuickToolBox

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

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

Вебхуки — это определяемые пользователем 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)
  );
}

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

Лучшие практики проверки подписи

Реализация надёжных повторных попыток

Сети дают сбои, серверы перезагружаются, а эндпоинты работают с тайм-аутом. Надёжная система вебхуков должна повторять неудачные доставки. Но повторные попытки могут вызывать дубликаты, поэтому вам нужна идемпотентность.

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

Большинство провайдеров используют экспоненциальную задержку с джиттером. Например, повтор через 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 вебхуки

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

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

  1. Настройте эндпоинт, который принимает POST-запросы по HTTPS.
  2. Проверьте подпись с использованием общего секрета и отклоняйте недействительные запросы с кодом 401.
  3. Проверьте временную метку, чтобы предотвратить атаки повторного воспроизведения.
  4. Отвечайте немедленно с кодом 200 OK после базовой проверки, затем обрабатывайте асинхронно.
  5. Реализуйте идемпотентность с использованием ID событий, чтобы избежать повторной обработки.
  6. Регистрируйте и отслеживайте сбои и повторные попытки.

Часто задаваемые вопросы

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

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

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

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

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

Нет, HTTPS необходим для защиты данных и подписи от перехвата и подделки. Всегда используйте TLS.

Готовы протестировать свои данные вебхуков? Используйте наш JSON-форматтер, чтобы быстро отформатировать и проверить JSON-данные.