Проверка подписи webhook: защита оплат и статусов онлайн-записи

Адрес обработчика webhook обычно доступен внешней системе через интернет. Знание этого адреса не является разрешением менять бронирования. Если обработчик принимает любое сообщение со статусом «оплачено», посторонний запрос может выглядеть так же, как штатное уведомление, даже без доступа к самому платёжному сервису.

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

У каждой точки приёма должен быть известен доверенный контекст: поставщик, среда, аккаунт и набор разрешённых событий. Тестовое уведомление не должно менять реальную запись, а сообщение одного подключённого бизнеса не должно попадать в данные другого. Эта граница важна даже при использовании одной общей интеграционной платформы.

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

Сначала выясните, какие байты и заголовки участвуют в вычислении подписи. GitHub описывает HMAC-SHA256 по содержимому запроса и общему секрету, передавая результат в X-Hub-Signature-256. В этой схеме проверяют именно согласованный алгоритм и представление подписи, используя безопасное сравнение значений.

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

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

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

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

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

Если протокол включает подписанную временную отметку, проверяйте её по документации и поддерживайте корректное время сервера. Stripe описывает такую проверку как меру против воспроизведения старых доставок. Это не универсальное свойство любой подписи: у другого поставщика защита от повторов может быть устроена иначе.

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

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

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

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

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