Webhook-интеграции¶
Требования применяются к разработке, тестированию и сборке webhook producer и
consumer. Уровни обязательности определены в корневом README.md.
INT-HOOK-001. Версионируемый контракт события¶
Уровень: MUST
Применяется к: каждому типу webhook
Producer должен публиковать машинно-проверяемую схему с типом, стабильным идентификатором события, версией, временем создания и payload. Контракт должен определять совместимость, порядок, возможность дубликата и максимальный размер.
Обоснование¶
HTTP-доставка не определяет семантику внешнего события.
Проверка¶
- schema validation producer и consumer;
- compatibility diff;
- contract-тест обязательных metadata.
Исключения¶
Не допускаются для публичного webhook.
INT-HOOK-002. Проверка подлинности доставки¶
Уровень: MUST
Применяется к: webhook consumer
Consumer должен проверять подпись над неизменёнными bytes тела и
контрактно определёнными metadata до parsing и обработки. Проверка должна
использовать constant-time comparison, ограниченное окно времени и защиту от
повторного использования идентификатора. Секрет подписи регулируется
SEC-SCRT-001, SEC-SCRT-002 и SEC-SCRT-005.
Обоснование¶
Знание URL endpoint не подтверждает источник запроса.
Проверка¶
- тест изменённого тела, подписи и времени;
- тест replay одного event ID;
- тест ротационного набора test keys.
Исключения¶
Асимметричная подпись может заменить shared secret при тех же проверках целостности и replay.
INT-HOOK-003. Идемпотентный consumer¶
Уровень: MUST
Применяется к: повторной доставке webhook
Consumer должен дедуплицировать событие по стабильному идентификатору. Фиксация необратимого эффекта и отметки обработки должна быть атомарной либо защищаться эквивалентным транзакционным контрактом. Порядок поступления не должен использоваться без явной гарантии контракта.
Обоснование¶
Producer повторяет доставку после неопределённого результата.
Проверка¶
- последовательный и конкурентный replay;
- тест crash между эффектом и ответом;
- тест перестановки событий.
Исключения¶
Не допускаются для необратимого эффекта.
INT-HOOK-004. Ограниченный producer¶
Уровень: MUST
Применяется к: исходящей доставке webhook
Producer должен задавать timeout, конечное число повторов с backoff и конечную локальную очередь. Успешной доставкой должен считаться только контрактно определённый HTTP-ответ. Redirect не должен автоматически следовать на endpoint вне разрешённой границы, а адрес назначения должен проверяться против Server-Side Request Forgery (SSRF).
Обоснование¶
Пользовательский endpoint является недоверенной и потенциально медленной зависимостью.
Проверка¶
- тест timeout, retry и заполнения очереди;
- тест redirect и адресов loopback/link-local;
- тест классификации HTTP-ответов.
Исключения¶
Нулевое число повторов допустимо для явно at-most-once контракта.
INT-HOOK-005. Минимизация и фильтрация payload¶
Уровень: MUST
Применяется к: созданию webhook payload
Payload должен содержать только поля опубликованной allowlist-схемы и не должен содержать secret, credential или внутренний объект целиком. Подписка должна ограничивать разрешённые типы событий; consumer input не должен управлять произвольным именем внутреннего события.
Обоснование¶
Webhook покидает границу проекта и сохраняется независимым потребителем.
Проверка¶
- schema и snapshot test payload;
- тест marker-секрета;
- security-тест фильтра подписки.
Исключения¶
Персональные данные допускаются только как явно классифицированные поля публичного контракта.