Самая частая причина mismatch — приложение подписывает JSON после parsing, а провайдер подписал исходные байты HTTP body. Остановите обработку перед `JSON.parse`: возьмите raw body, заголовок подписи и secret конкретного endpoint. Любое изменение пробелов, порядка ключей или кодировки меняет HMAC.
Не отключайте проверку, чтобы «посмотреть payload» в production. Создайте тестовый delivery, логируйте только delivery ID, размер, SHA-256 raw body и результат проверки. Содержимое события может включать персональные и платёжные данные.
Mismatch раскладывается на пять входов
| Вход | Типовая ошибка | Как подтвердить |
|---|---|---|
| Raw body | Parser пересобрал JSON | Hash bytes до middleware |
| Secret | Взят ключ другого endpoint/режима | Сверить endpoint ID и окружение |
| Header | Прочитан legacy или другой алгоритм | Имя и формат из docs провайдера |
| Signed message | Пропущен timestamp/prefix | Официальная схема формирования |
| Compare | Обычное равенство или разный encoding | Bytes/hex/base64 и constant-time |
Stripe отдельно предупреждает: body должен остаться UTF-8 строкой без изменений; GitHub рекомендует `X-Hub-Signature-256` и HMAC-SHA256. Эти форматы нельзя смешивать. Универсальный verifier, который угадывает схему по длине digest, опаснее маленьких адаптеров по провайдерам.
Middleware подключается после webhook route
# Псевдокод: конкретный формат берётся из документации провайдера
raw = request.body_bytes_before_parsing()
signature = request.header("Provider-Signature")
secret = secret_store.for_endpoint(endpoint_id)
expected = HMAC_SHA256(secret, raw)
if !constant_time_equal(expected, decode(signature)):
return 401
event = parse_json(raw)Псевдокод намеренно не задаёт имя header и signed payload: у Stripe в подпись входит timestamp и тело, у GitHub формат имеет префикс `sha256=`. Предпочтите официальную SDK-функцию, потому что она также проверяет формат, версии подписи и допустимое окно времени там, где оно предусмотрено.
Proxy и serverless gateway тоже могут менять тело
- Проверьте decompression, charset conversion и body mapping template.
- Не pretty-print JSON и не конвертируйте числа через промежуточный объект.
- Сохраните порядок middleware: raw reader раньше JSON parser.
- Сравните Content-Length и hash на границе proxy и приложения.
- Убедитесь, что verification получает bytes, а не строку после неверной перекодировки.
Если gateway отдаёт одновременно parsed body и rawBody, verifier использует rawBody. Base64-флаг учитывается до HMAC: подпись считают по восстановленным исходным байтам, а не по base64-тексту, если документация платформы говорит, что body закодирован для транспорта.
Secret привязан к endpoint и окружению
CLI forwarding, dashboard test mode и production endpoint могут иметь разные secrets. Храните связь provider + account + endpoint ID + secret version. Не выбирайте ключ по полю из непроверенного payload: этот payload ещё не аутентифицирован.
При ротации временно проверяйте активную и предыдущую версии в фиксированном порядке, но подписывайте исходящие тесты только текущей. Логируйте номер версии, не сам ключ. После окна доставки удалите старую версию и проверьте, что отложенные retries не потерялись.
Timestamp ограничивает replay, delivery ID — дубли
Криптографическая подпись подтверждает байты и знание secret, но обработчик всё равно должен дедуплицировать повторные доставки по устойчивому event/delivery ID. Если схема содержит timestamp, проверяйте его после валидной подписи и с разумной синхронизацией часов; не принимайте бесконечное окно ради редких задержек.
Приёмка включает отрицательные тесты
Отправьте официальный test delivery, повтор того же delivery, payload с изменённым одним байтом, запрос без header и запрос со старым secret. Ожидайте: первый обрабатывается один раз, повтор возвращает безопасный 2xx без дубля операции, остальные получают 4xx и не доходят до бизнес-логики.
Для разбора достаточно provider, endpoint ID, имён headers, размера/hash raw body, версии secret и delivery ID. Payload, secret, подпись целиком, cookies и authorization headers передавать не нужно.