HMAC-подпись — это не галочка, а фильтр от мусорных хуков

HMAC-подпись — это не галочка, а фильтр от мусорных хуков

Если входящий вебхук не проверяет подпись, любой может постучаться в endpoint и сымитировать “легитимное” событие. Результат предсказуем: ложные заказы, дубли, подмена payload и весёлый дебаг в три часа ночи. Смотрим в тело запроса, но сначала проверяем, что это вообще наш отправитель.

Базовый алгоритм простой: берёте raw body без парсинга, считаете HMAC на стороне приёмника тем же алгоритмом, сравниваете с подписью из заголовка. Заголовок может называться по-разному: X-Signature, X-Hub-Signature-256, Authorization. Важно не имя, а канонизация: одинаковая строка, одинаковая кодировка, одинаковый secret. Любой пробел, лишний перенос строки или JSON-пересборка ломают верификацию.

Критичные правила:
— сравнение только через constant-time function, иначе получите лишний канал утечки;
— secret хранить как секрет, не в коде и не в логах;
— проверять timestamp, если он есть, и отклонять старые запросы;
— принимать только один идентификатор события и строить идемпотентность поверх него. Идемпотентность — это не роскошь, а база.

Если подпись не сошлась — сразу 401/403, без ретраев в бизнес-логику. Если всё ок — класть событие в очередь, а не обрабатывать синхронно. Ретрай-политика решает всё: сначала auth, потом уже пайплайн. Ловим 5xx на ровном месте не на входе, а внутри системы, где их можно нормально переиграть.

Правильная подпись не делает интеграцию удобной. Она делает её живой. После неё остаётся только одна задача: не сломать себе же проверку при очередном “безобидном” изменении middleware.