Вебхуки: подписанные payload'ы и надёжные повторы
Вы запускаете интеграцию платежей, и всё работает на стейджинге. Но в продакшене клиент оплачивает, ваш эндпоинт отваливается по таймауту на две секунды, и заказ так и не активируется. В это же время платёжный провайдер повторяет то же событие три раза, и ваше приложение создаёт три дубликата заказа для того, который всё-таки прошёл. Вебхуки кажутся простыми — просто 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-подпись над сырым телом запроса с использованием общего секрета, который знаете только вы и провайдер. Провайдер вычисляет подпись и отправляет её в заголовке; вы пересчитываете её и сравниваете.
Как правильно проверять подпись
Три детали легко упустить:
- Используйте сырое тело. Разбирайте JSON только после проверки. Повторная сериализация разобранного объекта меняет пробелы и порядок ключей, поэтому подпись никогда не совпадёт.
- Сравнивайте за постоянное время. Наивное сравнение строк утекает информацию о времени. Используйте функцию, устойчивую к атакам по времени.
- Включайте метку времени в подписываемую строку. Подпись
timestamp.bodyпозволяет отклонять старые запросы и блокирует атаки повторного воспроизведения.
// Пример для 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, генерация счетов — должна выполняться в фоновой задаче. Если обработка занимает больше времени, чем таймаут провайдера, запрос считается неудачным и повторяется, даже если вы всё сделали.
- Проверьте подпись и метку времени.
- Вставьте событие в таблицу с уникальным ограничением по ID события.
- Немедленно верните
200. - Обработайте сохранённое событие асинхронно, отметив его как выполненное.
Идемпотентность: настоящее решение проблемы дубликатов
Поскольку повторы случаются, ваш обработчик должен быть безопасен при двойном запуске. 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 и дайте повтору сделать свою работу.
Практический чек-лист для продакшена
- Используйте только HTTPS; никогда не принимайте вебхуки по обычному HTTP.
- Храните секрет подписи в менеджере секретов и поддерживайте ротацию — многие провайдеры допускают два активных секрета.
- Логируйте ID события, тип, результат проверки подписи и результат обработки для каждого запроса.
- Установите окно допустимого времени (обычно пять минут), чтобы блокировать повторы.
- Делайте обработчики идемпотентными на уровне базы данных, а не только в коде приложения.
- Настройте оповещения при превышении порога частоты ошибок или задержки обработки.
- Предоставьте эндпоинт для ручного повтора для службы поддержки.
Тестирование вебхуков локально
Вы не можете легко получить публичный POST на localhost. Варианты: инструмент туннелирования, открывающий ваш порт разработки, CLI провайдера, если он есть, или небольшой скрипт, который отправляет подписанный payload вашему обработчику, чтобы вы могли проверить путь проверки подписи.
Самый ценный тест — дубликат: отправьте одно и то же событие дважды и убедитесь, что ваша система приходит в одно и то же состояние. Затем отправьте событие со старой меткой времени и убедитесь, что оно отклонено. Затем измените один байт тела и убедитесь, что проверка подписи не проходит.
Отладка payload'ов
Тела вебхуков — это JSON, и некорректные или глубоко вложенные payload'ы трудно читать в логах. Форматтер помогает быстро изучить структуру перед написанием кода разбора. JSON-форматтер работает в браузере, поэтому вы можете вставить захваченный payload, не отправляя данные клиентов на сервер.
Часто задаваемые вопросы
В чём разница между вебхуком и API?
API работает по принципу запроса: ваш код вызывает провайдера, когда ему нужны данные. Вебхук работает по принципу push: провайдер вызывает ваш эндпоинт, когда происходит событие. Большинство интеграций используют оба подхода — вебхуки для уведомлений о событиях и API для получения полных деталей или выполнения действий.
Почему моя HMAC-подпись никогда не совпадает?
Обычная причина — подпись повторно сериализованного тела вместо сырых байтов. Пробелы, порядок ключей и экранирование Unicode меняют хеш. Читайте сырое тело запроса до любого JSON-middleware и убедитесь, что секрет и алгоритм хеширования соответствуют документации провайдера.
Гарантированы ли повторные попытки вебхуков?
Нет. Провайдеры обычно повторяют попытки в течение ограниченного окна с экспоненциальной задержкой, а затем сдаются. Относитесь к вебхукам как к быстрому каналу уведомлений, а не как к источнику истины: периодически сверяйтесь с API провайдера, чтобы пропущенные события в конечном итоге были исправлены.
Если вы сегодня создаёте или отлаживаете приёмник вебхуков, начните с укрепления проверки подписи и идемпотентного хранения — эти два изменения устраняют большинство реальных инцидентов с вебхуками.