техническое · ответ с источниками

Проверка подписи вебхука

Проверка подписи вебхука — процесс безопасности, при котором получатель проверяет криптографическую подпись, приложенную к входящему HTTP-запросу. Так он убеждается, что полезная нагрузка отправлена доверенным провайдером и не была изменена при передаче.

Определение

Проверка подписи вебхука — механизм аутентификации источника события вебхука. Когда провайдер вроде Resend или SendGrid отправляет уведомление о событии письма, он включает хеш полезной нагрузки, подписанный секретным ключом. Принимающий сервер с помощью того же секретного ключа заново вычисляет хеш и сравнивает его с подписью из заголовка запроса.

Как устроен процесс

Провайдер вычисляет HMAC-хеш на основе общего секрета и тела запроса. Этот хеш передаётся в заголовке, который часто называется X-Signature или похожим образом. Получатель сохраняет исходное тело запроса и заголовок подписи, а затем вычисляет собственный HMAC-хеш с помощью общего секрета. Если вычисленный хеш совпадает со значением заголовка, запрос подлинный. Если нет, запрос отклоняется как неавторизованный.

Почему это важно для отправителей

Без проверки любой, кто знает URL вашего вебхука, может отправить на ваш сервер поддельные данные. Это может привести к неверным обновлениям базы данных, например доставленное письмо будет помечено как отказ. Проверка подписи предотвращает атаки с подделкой и гарантирует, что ваше приложение реагирует только на легитимные события от вашей почтовой инфраструктуры.

Заметки по эксплуатации

Распространённая ошибка — разбирать тело запроса в JSON-объект до проверки подписи. Поскольку JSON-парсеры могут менять пробелы или порядок ключей, итоговая строка может не совпасть с исходной полезной нагрузкой, которую использовал провайдер. Всегда используйте для вычисления HMAC исходное, неразобранное тело запроса, чтобы избежать сбоев проверки.

Пример реализации

В среде Node.js разработчик использует модуль crypto, чтобы вычислить HMAC SHA-256 от исходного тела с секретом провайдера. Затем результат сравнивается с заголовком подписи функцией сравнения за постоянное время, чтобы предотвратить атаки по времени. SendHQ предлагает бесплатные инструменты на https://sendhq.cc/tools, которые помогают управлять различными настройками почты, обычно предшествующими настройке вебхуков.

Что спрашивают команды

Что будет, если секретный ключ утёк?

Если секретный ключ скомпрометирован, злоумышленник может подписывать поддельные запросы, которые ваш сервер примет как действительные. Немедленно смените секретный ключ в панели управления провайдера и обновите переменные окружения на сервере.

Заменяет ли HTTPS проверку подписи?

Нет. HTTPS шифрует данные при передаче и подтверждает подлинность сервера, но не проверяет, что клиент, отправляющий запрос, — именно ваш авторизованный почтовый провайдер.

Почему HMAC, а не просто API-ключ?

HMAC-подписи доказывают, что содержимое сообщения не было подделано. Статичный API-ключ в заголовке доказывает лишь то, что отправитель знает ключ, но не то, что полезная нагрузка не изменена.

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

Документация Resend — Resend
Документация для разработчиков Postmark — Postmark
Документация SendGrid — Twilio SendGrid