Подпись вебхука: что проверить до изменения заказа

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

Сначала найдите контракт отправителя

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

Например, GitHub описывает проверку вебхуков через общий секрет и HMAC-SHA256, значение передаётся в X-Hub-Signature-256. В руководстве также рекомендуется безопасное сравнение и обработка Unicode. Это правила GitHub, а не обязательный формат любой подписи. Для реализации лучше взять поддерживаемую библиотеку поставщика, если она подходит выбранному окружению.

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

Что происходит с телом до проверки

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

У Stripe в документации вебхуков прямо указан raw body для проверки. Там же описана подписанная временная метка и её проверка по правилам сервиса. Эти сведения приведены как пример различий протоколов, без рекомендации платёжного провайдера. Нельзя добавить произвольный неподписанный timestamp и считать его равнозначной защитой.

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

Четыре вопроса перед рабочим изменением

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

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

Таблица отрицательных испытаний

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

Подтверждённое событие тоже может быть повтором

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

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

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

Порядок разработки и приёмки

1. Сохраните ссылку на официальный контракт поставщика и список подключений. Укажите, откуда берётся секрет и какие окружения допустимы для испытаний.
2. Проверьте путь получения тела и заголовков до рабочих изменений. Используйте подходящую поддерживаемую реализацию проверки, не собственное сравнение по внешнему виду строки.
3. После успешной проверки валидируйте тип события, организацию, объект и разрешённый переход. Согласуйте работу с неизвестными типами и неполными данными.
4. Определите идентификатор повторной обработки и целостную фиксацию результата. Отдельно опишите сбой, одновременный приём и восстановление незавершённого действия.
5. Пройдите таблицу учебных случаев. Для каждого подтвердите результат в данных, а не только ответ HTTP или зелёную строку тестового инструмента.
6. Примите журнал отказов без секретов и лишнего содержимого. У поддержки должен быть способ различить неверное подключение, изменённое тело и недопустимое событие.

Что должно быть видно при неисправности

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

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

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