РУКОВОДСТВО · ОБНОВЛЕНО 2026-10-31
Подпись webhook от AI-сервиса: как проверить тело до обработки события
Контракт входящего события, который проверяют до изменения состояния задания.
Входящий webhook нельзя считать подлинным только потому, что он пришёл на трудноугадываемый URL. Если поставщик поддерживает подпись, проверяйте её по его документации над теми байтами, которые он действительно подписал. Для многих HMAC-схем это исходное тело запроса, иногда вместе с меткой времени. Разобранный и заново сериализованный JSON может отличаться. Проверка подписи и защита от повторной обработки решают разные задачи: одна подтверждает сообщение, другая не позволяет второй доставке повторно изменить состояние вашего приложения.
1. Уточните документированный контракт
Проверьте алгоритм, имя заголовка, формат подписи и состав подписанных данных. Не переносите пример GitHub на AI-поставщика автоматически: он иллюстрирует HMAC, но другой сервис может использовать иной протокол. Определите допустимый размер тела и способ чтения raw body в вашем фреймворке. Наличие callback URL в настройках ещё не означает поддержку криптографической подписи. Если её нет, выбирайте предусмотренный поставщиком способ проверки статуса задания и ограничьте полномочия входящего события.
2. Сохраните тело до преобразований
Получите исходные байты до обычного JSON middleware, если того требует схема. Не меняйте пробелы, порядок полей и кодировку перед вычислением ожидаемой подписи. Проверьте формат полученного значения и сравнивайте его подходящей функцией с постоянным временем с учётом требований библиотеки. Ошибка проверки должна остановить обработку до изменения состояния задания. Секрет webhook храните на сервере; не помещайте его в промпт, публичный JavaScript или диагностическое сообщение об ошибке.
3. Отделите подлинность от повторов
Сохраните идентификатор доставки или события и применяйте переход состояния идемпотентно. Настоящее подписанное сообщение тоже может быть доставлено повторно. Если схема включает время, проверяйте его по документированным правилам поставщика, не придумывая универсальное окно для всех сервисов. Для события с неизвестным заданием не создавайте автоматически оплачиваемую операцию. Свяжите событие с существующей записью и разрешённым переходом. Не считайте дубликат поводом снова запускать генерацию или скачивание результата.
4. Проверьте приём и восстановление
Используйте опубликованный тестовый вектор или синтетическое тело с локальным секретом. Проверьте изменённый байт, неверный формат подписи, пропущенный заголовок и повтор одной доставки. Отдельно проверьте сбой после принятия события: обработка должна возобновляться без повторного внешнего эффекта. Подтверждение приёма отправляйте согласно контракту сервиса и правилам вашей очереди. В журнале оставляйте безопасный идентификатор и причину отказа, а не полное тело с пользовательскими документами и секретами.
Частые вопросы
Можно ли проверить подпись после JSON.parse?
Если подписаны исходные байты, нужен raw body до преобразования. Повторная сериализация JSON может дать другое представление тех же данных.
Заменяет ли подпись идемпотентность?
Нет. Подпись подтверждает сообщение, но не запрещает его повторную доставку. Дубликаты нужно учитывать отдельным механизмом состояния.
Нужно ли везде использовать HMAC-SHA256?
Используйте только алгоритм и формат, которые документирует выбранный поставщик. Чужой пример не является контрактом вашего webhook.
Можно ли сообщить модели секрет для проверки?
Нет. Проверку выполняет серверная реализация. Модели достаточно безопасного статуса результата, без ключа подписи и необязательных чувствительных полей.