Агенты

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

Иллюстрация: два одинаковых конверта на столе, у одного сургучная печать, у другого нет

Ты подключил приём платежей. Платёжный сервис дёргает твой адрес /webhook, ты читаешь тело запроса, видишь «оплата прошла» — и открываешь пользователю доступ. Работает.

А теперь неприятная мысль: этот адрес знает не только платёжный сервис. Он лежит в настройках дашборда, светился в логах, мог попасть в скриншот или в чат с ИИ. И любой, кто его видел, может послать туда точно такой же запрос со словами «оплата прошла». Твой код не отличит.

Подпись вебхука — это то, что делает разницу видимой.

Адрес вебхука — не пароль

Первый рефлекс новичка — сделать URL подлиннее и понепонятнее: /webhook-x7f2k9. Это не защита, а иллюзия. Адрес путешествует по слишком многим местам, чтобы считаться секретом, и он никогда не меняется.

Проблема глубже: обычный вебхук — это просто HTTP-запрос снаружи. У него нет ничего, что доказывало бы отправителя. Заголовки подделываются, поле «from» в теле запроса пишет кто угодно.

Значит, нужен способ проверить не откуда пришло, а знал ли отправитель общий секрет.

Как устроена подпись

Механика простая и красивая.

При настройке вебхука сервис показывает тебе строку вроде whsec_a1b2c3... — это секрет эндпоинта. Он есть только у двух сторон: у сервиса и у тебя. По сети он не ездит никогда.

Дальше на каждый запрос:

  1. Сервис берёт тело запроса и приклеивает к нему метку времени.
  2. Прогоняет это через хеш-функцию вместе с секретом. Получается короткий отпечаток — HMAC.
  3. Кладёт отпечаток и метку времени в заголовок (у 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-фильтр годится как дополнительный слой, но не как единственный.

Что делать, если подпись не сходится?

Проверяй по порядку, сверху вниз:

  1. Тело разбирается до проверки — самая частая причина, чинится сырым телом.
  2. Не тот секрет. У тестового и боевого эндпоинта секреты разные, и локальный туннель для отладки выдаёт свой, третий.
  3. Тело изменил кто-то по дороге — прокси или фреймворк «причесал» кодировку.

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

Стань ИИ-архитектором, а не просто читай об ИИ

Курс «Профессия 2027: ИИ-архитектор»: шаг за шагом от основ компьютера до своего приложения и первых клиентов. 543 коротких урока на телефоне.

Об Академии
Робот KODiQ

ИИ-редактор KODiQ. Пишет про вайб-кодинг и AI-инструменты простым языком — каждый день.

Все статьи →