В одном из наших продакшен-сценариев вебхуки платёжного сервиса проходят через Adal Server и Adal CLI, а затем поступают в конечный обработчик. HMAC-подпись успешно проверяется после прохождения всей цепочки — это практическое подтверждение того, что подписанные данные доставляются без изменений.
Вебхук может сообщать об успешной оплате, возврате, отмене или изменении статуса операции. Конечному приложению важно убедиться, что запрос действительно отправлен платёжным сервисом и что значимые данные не были изменены по пути. Для этого провайдеры обычно подписывают вебхуки с помощью HMAC.
Недавний продакшен-кейс показал, как эта проверка работает, когда между платёжным сервисом и обработчиком находится Adal.
Зачем использовать промежуточный слой
Маршрут запроса в этом сценарии выглядит так:
Платёжный сервис → Adal Server → Adal CLI → обработчик вебхука
Adal Server принимает запрос на постоянный публичный HTTPS URL. Запрос сохраняется и передаётся через Adal CLI в закрытое окружение, где работает конечный обработчик.
Такой маршрут решает сразу несколько задач:
вебхук принимается независимо от текущей доступности конечного обработчика;
входящий Request и состояние его доставки видны в интерфейсе;
неуспешную доставку можно повторить;
закрытому окружению не нужен публичный входящий адрес или открытый порт;
при необходимости можно изучить заголовки, тело запроса и историю попыток доставки.
Наблюдаемость и повторные попытки особенно важны для платёжных событий. Но у промежуточного слоя есть ещё одно обязательное свойство: он не должен незаметно преобразовывать данные, от которых зависит проверка подписи.
Что проверяет HMAC
Точная схема подписи определяется платёжным сервисом. Обычно отправитель вычисляет HMAC на основе тела запроса и общего секрета. В некоторых реализациях в подписываемую строку также входят timestamp или другие значения.
Получатель формирует подпись заново по тем же правилам и сравнивает результат с подписью, переданной отправителем. Если подписанное тело изменить — например, разобрать JSON, а затем сериализовать его с другим форматированием, — проверка, как правило, завершится ошибкой. То же относится к другим полям, если они участвуют в подписи конкретного провайдера.
В рассматриваемом сценарии HMAC проверяется конечным обработчиком после прохождения всего маршрута:
приём → сохранение → передача через CLI → доставка → HMAC-проверка
Проверка проходит успешно.
Это означает, что данные, включённые платёжным сервисом в подпись, дошли до обработчика в исходном виде. В частности, Adal не разобрал JSON и не собрал его заново, не изменил форматирование payload и не выполнил другое скрытое преобразование, которое нарушило бы подпись.
Практический end-to-end тест
Сохранение исходного тела можно проверять автоматическими тестами: отправлять заранее подготовленные данные и сравнивать результат на стороне получателя. Такие тесты необходимы, но реальный платёжный вебхук дополняет их сквозной проверкой работающей системы:
запрос сформирован внешним сервисом;
подпись рассчитана этим сервисом по его правилам;
запрос принят публичным Adal Server;
Request сохранён и передан по реальному продакшен-маршруту;
конечное приложение независимо проверило подпись.
Таким образом проверяется не отдельная функция в изолированной среде, а вся цепочка доставки.
При этом важно не делать из результата более широкий вывод, чем позволяет механизм подписи. HMAC подтверждает неизменность тех частей запроса, которые входят в схему подписи конкретного провайдера. Он не доказывает побитовое равенство каждого элемента HTTP-соединения: некоторые транспортные заголовки могут формироваться заново на каждом участке маршрута.
Для webhook payload и других подписанных значений успешная проверка остаётся сильным и практически значимым подтверждением корректной доставки.
Без скрытых преобразований
Один из принципов Adal — предсказуемая доставка вебхуков без скрытого переписывания payload.
В этом продакшен-сценарии принцип подтверждается поведением всей системы: Adal принимает запрос, сохраняет его, показывает историю доставки и передаёт его через CLI, после чего конечный обработчик продолжает успешно проверять HMAC платёжного сервиса.
Именно этого мы ожидаем от инфраструктуры доставки вебхуков: она должна добавлять надёжность и наблюдаемость, не меняя смысл и подписанные данные запроса.