Перейти к содержимому

Проверка подписи вебхуков с помощью HMAC

Заголовок X-Signature вебхука Chaingateway позволяет проверить, что запрос действительно пришёл от Chaingateway. Он содержит HMAC-SHA256 идентификатора транзакции (txid) из данных уведомления, закодированный в base64 и вычисленный с вашим личным секретом в качестве ключа. Ваш приёмник заново вычисляет значение и сравнивает его с заголовком. Заголовок отправляется после того, как вы задали личный секрет.

Проверка подписи: Chaingateway вычисляет HMAC-SHA256 от txid с вашим личным секретом и отправляет его в X-Signature, ваш приёмник заново вычисляет значение и сравнивает его за постоянное время Chaingateway подписывает base64( HMAC-SHA256( personal_secret, txid ) ) POST на ваш приёмник тело JSON с txid, заголовок X-Signature Приёмник заново вычисляет HMAC тот же секрет, тот же txid Сравнение за постоянное время равны: принять, различаются: отклонить с кодомошибки
Подписывается только txid. Остальные поля данных в подпись не входят.

Он защищает от поддельных запросов: отправить POST на публичный URL вашего приёмника может кто угодно, но подходящую подпись создаст только тот, кто знает личный секрет. HMAC, определённый в RFC 2104, объединяет хеш-функцию с секретным ключом, здесь это SHA-256. NIST FIPS 198-1 описывает ту же конструкцию как Keyed-Hash Message Authentication Code.

Подпись охватывает txid и ничего больше. Сумма, адреса и поля токена в теле не подписываются. Поэтому действительная пара txid и подписи не доказывает, что остальная часть тела не изменена. После проверки используйте txid как ключ поиска: прочитайте транзакцию запросом GET /api/v2/{chain}/transactions/{txid} и зачисляйте платёж по данным, которые вернул API, а не по сумме из тела уведомления.

Личный секрет задаётся или создаётся заново в настройках профиля. Выполните следующие шаги:

  1. Откройте настройки профиля.
  2. Найдите раздел «Personal Secret».
  3. Если секрет не задан, нажмите «Set Personal Secret», чтобы создать его. Если секрет уже есть, нажмите «Regenerate Secret», чтобы заменить его.

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

Chaingateway читает txid из данных уведомления, вычисляет над ним HMAC с хеш-функцией SHA-256, используя личный секрет в качестве ключа, и кодирует 32 байта результата в base64. Txid — это уникальный идентификатор транзакции, который уже есть в теле вебхука, поэтому у приёмника есть всё необходимое для повторного вычисления значения. Секрет известен только Chaingateway и вам.

Вычислите HMAC заново по txid из тела и сравните его со значением заголовка. Используйте функцию сравнения за постоянное время, чтобы время сравнения ничего не раскрывало об ожидаемом значении. Примеры ниже делают это на Python, Java, PHP и JavaScript.

import hmac
import hashlib
import base64
def verify_signature(txid, received_signature, personal_secret):
# Generate the expected signature
expected_signature = base64.b64encode(hmac.new(
personal_secret.encode(),
txid.encode(),
hashlib.sha256
).digest()).decode()
# Compare the expected signature with the received signature
return hmac.compare_digest(expected_signature, received_signature)
# Example usage
txid = 'your_txid_here'
received_signature = 'received_signature_here'
personal_secret = 'your_personal_secret_here'
if verify_signature(txid, received_signature, personal_secret):
print("Signature is valid.")
else:
print("Invalid signature.")

Проверьте функцию на фиксированном входе, прежде чем подключать её к реальному трафику. Значения ниже — тестовый вектор, который можно воспроизвести любым инструментом HMAC-SHA256. Секрет — это заглушка, а не настоящий личный секрет. Если ваша функция возвращает для этого входа другое значение, ошибка в вашем коде, а не в вебхуке.

personal_secret: my_personal_secret
txid: 18f52f2a55b94a6e3705de4abb18e95dfce79970f27b29450705c561e12b6988
X-Signature: t2vU2mYBCv/UvpKprNJB7qbgrCpPXKb6NWgL77xsZgQ=

Типичные ошибки: хеширование всего тела JSON вместо txid, использование hex-представления вместо base64 и сравнение через ==, которое выполняется не за постоянное время. Помните также, что личный секрет действует для всего аккаунта. Секрет, который вы создали заново в настройках профиля, одновременно меняет подпись всех вебхуков аккаунта.

Отклоните запрос с кодом ошибки, например 401 или 403, и не обрабатывайте тело. Записывайте в лог txid, полученный заголовок и адрес источника, чтобы отличить неверно настроенный секрет от поддельного запроса. Если один и тот же отправитель даёт несовпадения сразу после того, как вы создали секрет заново, приёмник всё ещё использует старый. Поддельный запрос, который лишь угадывает txid, не может создать действительную подпись без секрета.

Проверка подписи — это один уровень защиты. Следующие меры покрывают остальной путь.

  • Обслуживайте приёмник по HTTPS, чтобы данные шифровались при передаче. REST Security Cheat Sheet от OWASP рекомендует HTTPS для каждого эндпоинта, который обрабатывает конфиденциальные данные.
  • Отклоняйте запросы с отсутствующим или неверным X-Signature с кодом ошибки и записывайте их в лог.
  • Используйте txid как ключ идемпотентности. Уведомление, которое вы отправляете повторно через POST /api/v2/{chain}/webhooks/notifications/{id}/retry, содержит тот же txid и не должно зачислять платёж дважды.
  • Храните личный секрет в хранилище секретов, а не в репозитории, и меняйте его, если он мог утечь. Chaingateway не повторяет неудавшиеся доставки самостоятельно, поэтому планируйте обновление приёмника и секрета как один шаг, а пропущенные уведомления затем отправьте повторно из списка неудавшихся.