Самая частая причина mismatch — приложение подписывает JSON после parsing, а провайдер подписал исходные байты HTTP body. Остановите обработку перед `JSON.parse`: возьмите raw body, заголовок подписи и secret конкретного endpoint. Любое изменение пробелов, порядка ключей или кодировки меняет HMAC.

Не отключайте проверку, чтобы «посмотреть payload» в production. Создайте тестовый delivery, логируйте только delivery ID, размер, SHA-256 raw body и результат проверки. Содержимое события может включать персональные и платёжные данные.

Mismatch раскладывается на пять входов

ВходТиповая ошибкаКак подтвердить
Raw bodyParser пересобрал JSONHash bytes до middleware
SecretВзят ключ другого endpoint/режимаСверить endpoint ID и окружение
HeaderПрочитан legacy или другой алгоритмИмя и формат из docs провайдера
Signed messageПропущен timestamp/prefixОфициальная схема формирования
CompareОбычное равенство или разный encodingBytes/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 передавать не нужно.

Проверенные источники