HMAC-подпись для вебхука: если не проверяете её, вы принимаете мусор за событие

HMAC-подпись для вебхука: если не проверяете её, вы принимаете мусор за событие

Входящий хук без валидации подписи — это открытый HTTP-эндпоинт с иллюзией доверия. Любой, кто знает URL, может прислать payload с нужным JSON и заставить ваш пайплайн делать работу за него. Смотрим в тело запроса, но сначала убеждаемся, что тело действительно пришло от того, кому вы верите.

Базовая схема простая: берёте raw body без парсинга, считаете HMAC по секрету, сравниваете с заголовком провайдера. Не используйте обычное `==` для сравнения — нужна constant-time проверка, иначе ловите side-channel на ровном месте. Пример логики: `sig = hmac.new(secret, raw_body, sha256).hexdigest()`, затем `compare_digest(sig, received_sig)`.

Типовые ошибки: парсить JSON до проверки подписи; менять тело запроса при нормализации пробелов и ключей; хранить секрет рядом с кодом, который логируется в CI; принимать старые подписи без окна по времени. Если провайдер шлёт timestamp, проверяйте его отдельно и режьте replay-атаки. Идемпотентность — это не роскошь, а база: даже валидный хук можно прислать повторно.

Минимальный боевой чек-лист: 1) raw body без мутации; 2) секрет из хранилища секретов, а не из конфига в репозитории; 3) постоянное время сравнения; 4) отказ 401/403 до любой бизнес-логики; 5) логирование только метаданных, без утечки подписи и payload. Ретрай-политика решает всё, но сначала убедитесь, что ретраить имеет смысл.

Если подпись не сошлась — не обрабатывайте событие, не спорьте с API и не «попробуйте ещё раз на всякий случай». Сначала криптография, потом очереди, потом бизнес-логика.