Материал обновлён 21 октября 2026 года.
После изменения репозитория GitHub отправляет вебхук в рабочую систему. Обработчик обновляет статус задачи или запускает служебную операцию. Такой адрес доступен из сети, поэтому запрос может прийти от любого отправителя. До обработки события приложение должно установить, что сообщение действительно связано с настроенным вебхуком и его содержимое сохранилось при передаче.
Что подтверждает подпись
В настройках вебхука GitHub и на принимающем сервере задают общий секрет. GitHub использует его для вычисления HMAC-подписи тела запроса. Получатель выполняет такое же вычисление и сравнивает результаты. При совпадении подтверждается целостность сообщения и знание общего секрета отправителем. Владельцу проекта полезно понимать эту границу: утечка секрета лишает такую проверку ожидаемого смысла.
Официальная документация GitHub описывает заголовок X-Hub-Signature-256 и подпись с префиксом sha256=. Проверку проводят до дальнейшей обработки события. Секрет хранят на сервере в защищённой конфигурации; его нельзя помещать в клиентский JavaScript, открытый репозиторий или примеры, которыми обмениваются сотрудники. В этой статье действующие значения не используются.
Сохраните исходные байты запроса
Подпись относится к исходному телу. Если обработчик сначала разбирает JSON, меняет порядок полей и снова собирает строку, полученная последовательность байтов может отличаться. Тогда корректное событие будет отклонено. При постановке задачи разработчику отдельно укажите получение исходного тела до преобразований, которые выполняет веб-фреймворк.
Учебное событие может содержать название тестовой задачи и статус "готово к проверке". Используйте вымышленный проект и отдельный секрет тестовой среды. После проверки подписи обработчик разбирает сообщение и определяет допустимое действие. Даже подлинное событие должно соответствовать ожидаемому типу, репозиторию и рабочему сценарию вашей интеграции.
В документации GitHub рекомендовано сравнение с постоянным временем выполнения, предусмотренное криптографической библиотекой. Обычное сравнение строк не подходит для реализации этой проверки. Самостоятельно придумывать криптографический алгоритм не требуется: разработчик выбирает штатные средства языка и следует документированному формату поставщика.
Отказ тоже должен быть предусмотрен
Для отказов согласуйте условия, при которых обработчик останавливается до изменения рабочей задачи.
| Проверка | Ожидаемое действие |
|---|---|
| Заголовок подписи отсутствует | Отклонить запрос до обработки события. |
| Формат заголовка неожиданный | Отклонить запрос; рабочую задачу не менять. |
| Подпись не совпала | Отклонить запрос; рабочую задачу не менять. |
Для диагностики достаточно записать технический идентификатор проверки, время и категорию отказа. Сам секрет и полное содержимое чувствительного события в журнал попадать не должны.
Планируя замену секрета, согласуйте порядок действий в обеих системах и способ наблюдения за доставками. Несогласованная замена создаёт период, когда корректные события будут получать отказ. Для небольшого процесса можно выбрать контролируемое окно обслуживания и заранее определить ответственного за проверку результата. Конкретная процедура зависит от возможностей поставщика и вашей инфраструктуры.
Что проверить перед подключением рабочих событий
Для приёмки подготовьте четыре случая и отдельно запишите ожидаемый результат каждого.
- Корректная подпись с неизменённым телом запроса.
- Изменённое тело при прежней подписи.
- Отсутствующий заголовок подписи.
- Неверный общий секрет.
Официальный пример GitHub содержит учебные значения для проверки вычислений. Используйте его отдельно от рабочих учётных данных. В каждом отрицательном сценарии результатом должен стать отказ до изменения бизнес-данных.
Затем отправьте событие через штатный механизм тестирования доставки GitHub и сопоставьте результат с журналом вашего обработчика. Проверьте текст с кириллицей, поскольку кодировка участвует в представлении тела. Успешная криптографическая проверка ещё не подтверждает правильность обновления задачи: для этого отдельно сверяют допустимый переход статуса и выбранный объект. Повторную доставку также учитывают отдельным правилом обработки.
Ответственного за ошибки доставки назначьте заранее. Ему понадобятся доступ к техническим статусам и понятный порядок связи с владельцем интеграции.
Проектирование вебхуков и интеграций рабочих систем можно обсудить с Семёном Дулесовым.
Какое действие в вашей интеграции должно выполняться только после проверки отправителя?