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

Backend2026-11-11TryQuickToolBox

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

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

Что такое вебхук на самом деле

Вебхук — это обратный вызов API. Вместо того чтобы ваш сервер каждую минуту опрашивал провайдера с вопросом «есть что-нибудь новое?», провайдер отправляет HTTP-запрос на URL, который вы зарегистрировали, когда происходит событие. Payload обычно в формате JSON, а тип события находится либо в теле, либо в заголовке.

POST /webhooks/payments HTTP/1.1
Host: api.example.com
Content-Type: application/json
X-Event-Id: evt_8f2c1a
X-Timestamp: 1735689600
X-Signature: t=1735689600,v1=5d41402abc4b2a76b9719d911017c592

{
  "id": "evt_8f2c1a",
  "type": "payment.succeeded",
  "created": 1735689600,
  "data": { "order_id": "ord_123", "amount": 4999, "currency": "USD" }
}

На стороне отправителя важны два проектных решения, и оба стоит проверить при оценке любого провайдера: подписывает ли он payload и повторяет ли запрос при ошибке?

Почему неподписанные вебхуки опасны

URL вашего вебхука публичен. Любой, кто его узнает, может отправить поддельное событие payment.succeeded и пометить неоплаченный заказ как оплаченный. Белый список IP-адресов немного помогает, но провайдеры меняют IP, работают за CDN, и стабильного списка вы можете не получить.

Надёжное решение — HMAC-подпись над сырым телом запроса с использованием общего секрета, который знаете только вы и провайдер. Провайдер вычисляет подпись и отправляет её в заголовке; вы пересчитываете её и сравниваете.

Как правильно проверять подпись

Три детали легко упустить:

// Пример для Node.js / Express
const crypto = require('crypto');

function verifySignature(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(
    header.split(',').map(p => p.split('='))
  );
  const timestamp = Number(parts.t);
  if (!timestamp) return false;

  // Отклоняем устаревшие запросы (защита от повторов)
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - timestamp) > toleranceSeconds) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`)
    .digest('hex');

  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1 || '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

app.post('/webhooks/payments', express.raw({ type: '*/*' }), (req, res) => {
  if (!verifySignature(req.body.toString(), req.get('X-Signature'), SECRET)) {
    return res.status(401).send('invalid signature');
  }
  const event = JSON.parse(req.body.toString());
  // ... обработка события
  res.status(200).send('ok');
});

Обратите внимание на middleware express.raw(). Если вы подключите express.json() перед этим маршрутом, тело уже будет разобрано, и проверка подписи молча провалится — очень распространённая ошибка.

Проектирование повторных попыток без потери событий

Доставка вебхуков работает по принципу «как минимум один раз», а не «ровно один раз». Сети падают, ваш деплой перезапускает контейнер, и провайдер не знает, был ли ваш ответ 200 настоящим. Поэтому провайдер повторяет попытки с экспоненциальной задержкой, часто в течение часов или дней.

Отвечайте быстро, обрабатывайте позже

Ваш эндпоинт должен делать минимум: проверить, сохранить сырое событие, вернуть 2xx. Тяжёлая работа — отправка писем, вызов других API, генерация счетов — должна выполняться в фоновой задаче. Если обработка занимает больше времени, чем таймаут провайдера, запрос считается неудачным и повторяется, даже если вы всё сделали.

  1. Проверьте подпись и метку времени.
  2. Вставьте событие в таблицу с уникальным ограничением по ID события.
  3. Немедленно верните 200.
  4. Обработайте сохранённое событие асинхронно, отметив его как выполненное.

Идемпотентность: настоящее решение проблемы дубликатов

Поскольку повторы случаются, ваш обработчик должен быть безопасен при двойном запуске. ID события — естественный ключ идемпотентности.

INSERT INTO webhook_events (event_id, type, payload, received_at)
VALUES ($1, $2, $3, now())
ON CONFLICT (event_id) DO NOTHING;

Если вставка затронула ноль строк, вы уже видели это событие — подтвердите его и двигайтесь дальше. Для бизнес-логики примените ту же идею: используйте ID заказа как уникальный ключ при активации платежа, чтобы второе событие не могло создать вторую активацию.

Осознанный выбор кодов состояния

СтатусПоведение провайдераКогда использовать
200 / 204Пометить как доставленноеСобытие принято (даже если уже обработано)
400Обычно без повтораНекорректный payload, который вы никогда не обработаете
401Обычно без повтораНесовпадение подписи — проверьте секрет
429Повтор с задержкойВы ограничиваете частоту запросов
500 / 503Повтор с задержкойВременная ошибка, БД недоступна, идёт деплой

Вернуть 200 для события, которое вы не смогли сохранить, — худший вариант: провайдер прекращает повторы, и событие теряется навсегда. Верните 5xx и дайте повтору сделать свою работу.

Практический чек-лист для продакшена

Тестирование вебхуков локально

Вы не можете легко получить публичный POST на localhost. Варианты: инструмент туннелирования, открывающий ваш порт разработки, CLI провайдера, если он есть, или небольшой скрипт, который отправляет подписанный payload вашему обработчику, чтобы вы могли проверить путь проверки подписи.

Самый ценный тест — дубликат: отправьте одно и то же событие дважды и убедитесь, что ваша система приходит в одно и то же состояние. Затем отправьте событие со старой меткой времени и убедитесь, что оно отклонено. Затем измените один байт тела и убедитесь, что проверка подписи не проходит.

Отладка payload'ов

Тела вебхуков — это JSON, и некорректные или глубоко вложенные payload'ы трудно читать в логах. Форматтер помогает быстро изучить структуру перед написанием кода разбора. JSON-форматтер работает в браузере, поэтому вы можете вставить захваченный payload, не отправляя данные клиентов на сервер.

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

В чём разница между вебхуком и API?

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

Почему моя HMAC-подпись никогда не совпадает?

Обычная причина — подпись повторно сериализованного тела вместо сырых байтов. Пробелы, порядок ключей и экранирование Unicode меняют хеш. Читайте сырое тело запроса до любого JSON-middleware и убедитесь, что секрет и алгоритм хеширования соответствуют документации провайдера.

Гарантированы ли повторные попытки вебхуков?

Нет. Провайдеры обычно повторяют попытки в течение ограниченного окна с экспоненциальной задержкой, а затем сдаются. Относитесь к вебхукам как к быстрому каналу уведомлений, а не как к источнику истины: периодически сверяйтесь с API провайдера, чтобы пропущенные события в конечном итоге были исправлены.

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