Что такое подпись вебхука — и почему без неё боту можно наврать про оплату

Ты подключил приём платежей. Платёжный сервис дёргает твой адрес /webhook, ты читаешь тело запроса, видишь «оплата прошла» — и открываешь пользователю доступ. Работает.
А теперь неприятная мысль: этот адрес знает не только платёжный сервис. Он лежит в настройках дашборда, светился в логах, мог попасть в скриншот или в чат с ИИ. И любой, кто его видел, может послать туда точно такой же запрос со словами «оплата прошла». Твой код не отличит.
Подпись вебхука — это то, что делает разницу видимой.
Адрес вебхука — не пароль
Первый рефлекс новичка — сделать URL подлиннее и понепонятнее: /webhook-x7f2k9. Это не защита, а иллюзия. Адрес путешествует по слишком многим местам, чтобы считаться секретом, и он никогда не меняется.
Проблема глубже: обычный вебхук — это просто HTTP-запрос снаружи. У него нет ничего, что доказывало бы отправителя. Заголовки подделываются, поле «from» в теле запроса пишет кто угодно.
Значит, нужен способ проверить не откуда пришло, а знал ли отправитель общий секрет.
Как устроена подпись
Механика простая и красивая.
При настройке вебхука сервис показывает тебе строку вроде whsec_a1b2c3... — это секрет эндпоинта. Он есть только у двух сторон: у сервиса и у тебя. По сети он не ездит никогда.
Дальше на каждый запрос:
- Сервис берёт тело запроса и приклеивает к нему метку времени.
- Прогоняет это через хеш-функцию вместе с секретом. Получается короткий отпечаток — HMAC.
- Кладёт отпечаток и метку времени в заголовок (у Stripe это
Stripe-Signature).
На твоей стороне ты делаешь ровно то же самое своим экземпляром секрета — и сравниваешь отпечатки. Совпало? Значит, тело запроса не тронуто и отправитель знал секрет. Не совпало — отвечай 400 и не делай ничего.
Ключевое свойство: отпечаток считается от содержимого. Подменил в теле сумму с 1 ₽ на 100 000 ₽ — отпечаток стал другим, подделать его без секрета невозможно.
На практике это одна строчка, библиотека сервиса делает всё сама:
const event = stripe.webhooks.constructEvent(rawBody, signatureHeader, endpointSecret);
Главная ловушка: разобранный JSON ломает подпись
Здесь спотыкаются почти все, и ошибка выглядит абсурдно: код правильный, секрет правильный, а подпись «не сходится».
Причина в слове raw. Отпечаток считается от байт в байт того тела, что отправил сервис. А типовая настройка сервера первым делом разбирает JSON в объект. Когда ты потом склеиваешь объект обратно в строку, получается другая строка: пробелы переставлены, порядок ключей может отличаться, экранирование другое. Смысл тот же — байты другие. Отпечаток не совпадает.
Поэтому для маршрута вебхука нужно отключить автоматический разбор тела:
// правильно — тело приезжает сырым
app.post('/webhook', express.raw({ type: 'application/json' }), handler);
// сломано — тело уже разобрано, подпись не сойдётся
app.post('/webhook', express.json(), handler);
Разобрать JSON ты сможешь сам — но после проверки подписи, а не до.
Метка времени: защита от повтора
Одной подписи мало. Представь, что злоумышленник один раз перехватил настоящий запрос «оплата прошла» — целиком, вместе с подписью. Подпись-то валидная. Он может слать её тебе снова и снова, начисляя себе доступ бесконечно. Это называется replay-атакой.
Ровно поэтому в подписываемую строку кладут метку времени: изменить её, не сломав подпись, нельзя. Твоя сторона проверяет, что запрос свежий — библиотеки по умолчанию принимают расхождение около пяти минут. Иногда этот допуск ставят в ноль, чтобы «убрать лишнее», — так проверка свежести отключается совсем. Не делай так.
Вторая половина защиты — на твоей стороне: храни идентификатор уже обработанного события и молча игнорируй повтор. Это полезно и без атак — сервисы честно ретраят доставку, если ты ответил ошибкой или долго думал.
А если у сервиса нет подписи?
Такое бывает — единого стандарта нет, каждый делает по-своему. Встретишь три варианта.
Подпись-отпечаток, как выше: GitHub кладёт её в заголовок X-Hub-Signature-256, Stripe — в Stripe-Signature. Это самый надёжный вариант.
Общий токен. Сервис просто шлёт в заголовке заранее оговорённую строку — так устроены, например, вебхуки Telegram. Слабее подписи: токен ездит по сети в каждом запросе, и если его перехватят, подделать сообщение сможет кто угодно. Но это несравнимо лучше, чем ничего. Важная деталь: сравнивай такой токен не обычным ===, а функцией сравнения за постоянное время — обычное сравнение выходит из цикла на первом несовпавшем символе, и по времени ответа секрет теоретически подбирается посимвольно. В стандартной библиотеке для этого есть готовая функция.
Ничего. Тогда единственная защита — не доверять содержимому запроса вообще. Пришло «оплата прошла»? Не верь телу письма: сходи в API сервиса и спроси сам, что там с этим платежом. Вебхук в таком режиме — это просто сигнал «пойди проверь», а не источник правды. Кстати, так стоит делать и при наличии подписи, если операция денежная.
И общее для всех вариантов: вебхук принимай только по HTTPS. По обычному HTTP и токен, и тело видны любому по дороге.
А просто проверить IP отправителя нельзя?
Можно, но это слабая замена. Списки адресов у сервисов меняются, из-за облаков и прокси один и тот же IP бывает общим для тысяч клиентов, а сам IP в заголовках подделывается легче, чем кажется. Подпись доказывает знание секрета — это сильнее. IP-фильтр годится как дополнительный слой, но не как единственный.
Что делать, если подпись не сходится?
Проверяй по порядку, сверху вниз:
- Тело разбирается до проверки — самая частая причина, чинится сырым телом.
- Не тот секрет. У тестового и боевого эндпоинта секреты разные, и локальный туннель для отладки выдаёт свой, третий.
- Тело изменил кто-то по дороге — прокси или фреймворк «причесал» кодировку.
Если запрос вообще не доходит и проверять нечего — это уже другая история, она разобрана в почему вебхук не срабатывает.
Курс «Профессия 2027: ИИ-архитектор»: шаг за шагом от основ компьютера до своего приложения и первых клиентов. 543 коротких урока на телефоне.





