Зачем публичным вебхукам криптографическая проверка
Вебхуки передают уведомления о событиях через стандартные HTTP-запросы в открытой сети. В отличие от закрытых внутренних сервисов, защищённых приватными подсетями, эндпоинт для вебхуков доступен из интернета. Ограничение доступа только по секретному URL или IP-адресу ненадежно: провайдеры часто меняют сетевые шлюзы, а статический адрес может подвергнуться сканированию или несанкционированным запросам.
Криптографическая подпись на основе HMAC переносит проверку подлинности на уровень приложения. Сервис-отправитель вычисляет хеш от тела запроса с использованием общего секретного ключа и передаёт значение в HTTP-заголовке. Сервер-получатель повторяет вычисление со своим ключом и принимает запрос только при полном совпадении результата.
Вычисление подписи по сырому телу запроса
Распространённая ошибка при проверке подписи — попытка валидировать данные после парсинга JSON. Парсеры могут изменить порядок полей, удалить незначащие пробелы или иначе нормализовать числа с плавающей точкой. Криптографический хеш чувствителен к каждому байту, поэтому малейшее расхождение делает подпись невалидной.
Сервер должен считывать исходный байтовый поток тела запроса до вызова любых библиотек сериализации. Хеш вычисляется исключительно по сырым байтам, и только после успешного подтверждения подлинности данные передаются на парсинг в структуры приложения.
Сравнение хешей в постоянное время
Обычные операторы сравнения строк завершают работу на первом несовпадающем символе. Это создает уязвимость к атакам по времени: злоумышленник измеряет микросекундные задержки ответа сервера и посимвольно подбирает корректное значение подписи.
Для проверки подлинности необходимо использовать функции сравнения в постоянное время, такие как hmac.compare_digest в Python или crypto.timingSafeEqual в Node.js. Они проверяют все байты строки независимо от позиции расхождения и гарантируют фиксированное время выполнения операции.
Защита от атак повторного воспроизведения
Даже корректно подписанный запрос может быть перехвачен в сети и отправлен повторно. Если сервер не проверяет актуальность вызова, злоумышленник может дублировать критические операции, такие как создание заказа или подтверждение статуса.
Для защиты от повторов отправитель добавляет в заголовок метку времени, которая включается в строку для формирования подписи. На стороне получателя проверка строится на двух механизмах:
- Контроль допустимого окна времени: сервер сверяет метку со своими системными часами и отклоняет устаревшие запросы.
- Идемпотентность по идентификатору: уникальный номер события или хеш сохраняется в кеше, предотвращая повторную обработку в пределах временного окна.
Хранение и бесшовная ротация секретных ключей
Секретный ключ для подписи генерируется криптографически стойким генератором случайных чисел и хранится в переменных окружения или специализированных хранилищах секретов. Ключи нельзя сохранять в кодовой базе репозитория. При плановой замене или компрометации секрета мгновенно обновить ключ на обеих сторонах интеграции невозможно без потери части событий.
Бесшовная смена ключей требует одновременной поддержки двух секретов на переходный период. Сервер-получатель проверяет входящую подпись сначала основным действующим ключом, а в случае неудачи — предыдущим ключом, и только при несовпадении обоих отклоняет запрос.
Быстрый ответ и асинхронная обработка в очереди
Провайдеры вебхуков ограничивают максимальное время ожидания ответа на HTTP-запрос. Если обработчик начинает синхронно выполнять тяжелые транзакции в базе данных или обращаться к сторонним API, отправляющая сторона прерывает соединение по таймауту и запускает повторные попытки отправки.
Эндпоинт должен проверить заголовки и цифровую подпись, отправить подтверждение статусом 200 или 202 и поместить проверенную полезную нагрузку в фоновую очередь задач. Разделение приёма и выполнения логики обеспечивает стабильность интеграции при любых пиковых нагрузках. Для Telegram-ботов выбор между вебхуками и getUpdates разобран в статье вебхук или long polling.