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-тест фильтра подписки.
Исключения¶
Персональные данные допускаются только как явно классифицированные поля публичного контракта.
INT-HOOK-006. Явная гарантия доставки¶
Уровень: MUST
Применяется к: webhook, потеря или задержка которого нарушает обязательный бизнес-результат
Проект должен зафиксировать идентифицируемую версию producer и фактическую гарантию доставки для выбранной конфигурации: момент успешной доставки, условия повторения, нарушения порядка и потери, максимальный возраст недоставленного события, а также поведение очереди при restart и переполнении.
Гарантия должна подтверждаться документацией зафиксированной версии и
integration-тестами отказов. Наличие retry или очереди само по себе не должно
называться at-least-once, если событие может быть потеряно до подтверждённой
доставки. Идемпотентность consumer должна считаться защитой от повторного
эффекта, но не доказательством полноты доставки.
Обоснование¶
Одинаковый HTTP webhook может иметь разные гарантии в зависимости от версии, режима и конфигурации producer; retry consumer не восстанавливает потерянное событие.
Проверка¶
- сопоставление контракта с документацией точной версии и фактической конфигурацией producer;
- отказ target или consumer, restart producer и достижение предела очереди в контролируемой среде;
- проверка, что заявленная гарантия не сильнее наблюдаемого результата тестов.
Исключения¶
Не допускаются для объявления гарантии обязательной доставки.
INT-HOOK-007. Восстановление пропущенной доставки¶
Уровень: MUST
Применяется к: webhook из INT-HOOK-006, фактическая гарантия которого
допускает потерю события до обязательного бизнес-результата
Проект должен восстанавливать пропущенные факты из authoritative источника
повторяемой reconciliation-процедурой либо получать их по независимому
сохраняемому каналу, контракт которого исключает потерю в пределах
максимального возраста из INT-HOOK-006.
Reconciliation должна задавать источник, стабильный ключ или позицию, максимальный интервал обнаружения, разрешённую область чтения и результат для отсутствующего, удалённого, изменённого и повторного объекта. Восстановление должно быть идемпотентным. Полномочия reconciliation должны ограничиваться необходимыми полями и операциями; чтение содержимого объекта запрещено, если обязательный результат определяется только разрешёнными metadata.
Если ни reconciliation, ни сохраняемый канал недоступны, webhook не должен быть единственным источником обязательного бизнес-результата.
Обоснование¶
Компенсация дубликатов не обнаруживает факт, который producer не доставил.
Проверка¶
- контролируемый пропуск события и восстановление результата из источника;
- повторный и конкурентный запуск reconciliation;
- тест недоступного источника, частичного результата и минимальных полномочий.
Исключения¶
Не допускаются для обязательного бизнес-результата.