Перейти к содержимому
← Все статьи
6 мин чтения

Безопасность вебхуков: подпись, верификация и защита входящих запросов

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

Зачем публичным вебхукам криптографическая проверка

Вебхуки передают уведомления о событиях через стандартные HTTP-запросы в открытой сети. В отличие от закрытых внутренних сервисов, защищённых приватными подсетями, эндпоинт для вебхуков доступен из интернета. Ограничение доступа только по секретному URL или IP-адресу ненадежно: провайдеры часто меняют сетевые шлюзы, а статический адрес может подвергнуться сканированию или несанкционированным запросам.

Криптографическая подпись на основе HMAC переносит проверку подлинности на уровень приложения. Сервис-отправитель вычисляет хеш от тела запроса с использованием общего секретного ключа и передаёт значение в HTTP-заголовке. Сервер-получатель повторяет вычисление со своим ключом и принимает запрос только при полном совпадении результата.

Вычисление подписи по сырому телу запроса

Распространённая ошибка при проверке подписи — попытка валидировать данные после парсинга JSON. Парсеры могут изменить порядок полей, удалить незначащие пробелы или иначе нормализовать числа с плавающей точкой. Криптографический хеш чувствителен к каждому байту, поэтому малейшее расхождение делает подпись невалидной.

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

Сравнение хешей в постоянное время

Обычные операторы сравнения строк завершают работу на первом несовпадающем символе. Это создает уязвимость к атакам по времени: злоумышленник измеряет микросекундные задержки ответа сервера и посимвольно подбирает корректное значение подписи.

Для проверки подлинности необходимо использовать функции сравнения в постоянное время, такие как hmac.compare_digest в Python или crypto.timingSafeEqual в Node.js. Они проверяют все байты строки независимо от позиции расхождения и гарантируют фиксированное время выполнения операции.

Защита от атак повторного воспроизведения

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

Для защиты от повторов отправитель добавляет в заголовок метку времени, которая включается в строку для формирования подписи. На стороне получателя проверка строится на двух механизмах:

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

Хранение и бесшовная ротация секретных ключей

Секретный ключ для подписи генерируется криптографически стойким генератором случайных чисел и хранится в переменных окружения или специализированных хранилищах секретов. Ключи нельзя сохранять в кодовой базе репозитория. При плановой замене или компрометации секрета мгновенно обновить ключ на обеих сторонах интеграции невозможно без потери части событий.

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

Быстрый ответ и асинхронная обработка в очереди

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

Эндпоинт должен проверить заголовки и цифровую подпись, отправить подтверждение статусом 200 или 202 и поместить проверенную полезную нагрузку в фоновую очередь задач. Разделение приёма и выполнения логики обеспечивает стабильность интеграции при любых пиковых нагрузках. Для Telegram-ботов выбор между вебхуками и getUpdates разобран в статье вебхук или long polling.

Вопросы

Частые вопросы

Не нашли ответ — спросите на созвоне или в Telegram.

Почему проверки IP-адреса отправителя недостаточно?

Сетевые адреса облачных платформ часто распределяются динамически или проходят через общие шлюзы нескольких арендаторов. Кроме того, IP-фильтрация не защищает от модификации тела запроса по пути. Криптографическая подпись гарантирует целостность данных и подтверждает знание общего секрета.

Какой HTTP-статус возвращать при недействительной подписи?

При ошибке проверки подписи или просроченной временной метке следует возвращать статус 400 или 401 с нейтральным сообщением об ошибке. Не следует передавать во внешний ответ детали проверки, алгоритм или подсказки о структуре ключа.

Как правильно передавать временную метку и подпись в заголовках?

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

Связанная услуга

Интеграции 1С, CRM и внешних API

Когда сотрудники переносят данные между системами вручную, ошибки и задержки становятся частью процесса. Автоматизируем обмен и сделаем его состояние понятным для вашей команды.

Об услуге
Другие статьи
6 мин чтения

Интеграция с 1С, amoCRM и ERP: архитектура надёжного обмена данными

Интеграция с 1С, amoCRM и маркетплейсами через API: организация очередей, обработка лимитов, идемпотентность запросов и сквозной мониторинг обмена данными.

Читать статью: Интеграция с 1С, amoCRM и ERP: архитектура надёжного обмена данными →
6 мин чтения

Идемпотентность API: как обрабатывать повторные запросы без дублей

Как работает идемпотентность API: заголовок Idempotency-Key, уникальные индексы в БД, повторы вебхуков и алгоритм exponential backoff с джиттером.

Читать статью: Идемпотентность API: как обрабатывать повторные запросы без дублей →
Контакт

Обсудим вашу задачу?

Тридцать минут созвона — и у вас есть понимание архитектуры, сроков и формата работы. Без обязательств.

Или напишите в Telegram →Читайте наш канал в Telegram →

Укажите Telegram или email, чтобы мы могли ответить.

Отвечаем в течение 15 минут.