← Блог
10 мин чтения
|
Опубликовано
|
Обновлено

Проверка подписи вебхуков с личным секретом

Задайте личный секрет, и Chaingateway подпишет каждый вебхук заголовком X-Signature. Как работает HMAC, проверка на Node.js и что она не покрывает.

Главы
C
Chaingateway Team
Эксперты по блокчейну

Проверил(а) Maurice Sobiera

Личный секрет — это ключ, который вы задаёте в профиле Chaingateway. Когда он создан, каждый исходящий вебхук несёт заголовок X-Signature: HMAC-SHA256 от ID транзакции, подписанный этим секретом и закодированный в Base64. Ваш сервер пересчитывает значение и сравнивает его. Совпадение показывает, что запрос пришёл от Chaingateway.

Зачем вебхукам нужна подпись?

Конечная точка вебхука — это публичный URL, и любой, кто его знает, может отправить на него запрос. Без проверки поддельный запрос «платёж получен» мог бы выдать товар или зачислить деньги на счёт. Общий секрет решает эту проблему. Ключ знают только Chaingateway и ваш сервер, поэтому только они могут создать совпадающую подпись. Конструкция — это HMAC, описанный в RFC 2104: хеш-функция в сочетании с секретным ключом.

Как задать личный секрет?

Откройте настройки профиля в панели управления, найдите карточку личного секрета для вебхуков и нажмите «Set Personal Secret». Чтобы заменить существующий секрет, нажмите «Regenerate Secret». Две детали из документации важны:

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

Как строится подпись?

Документированная процедура состоит из трёх шагов. Прочитайте поле txid из полезной нагрузки вебхука. Вычислите HMAC-SHA256, где ключом служит ваш личный секрет, а сообщением — строка txid. Закодируйте результат в Base64 и сравните его с заголовком. Полезная нагрузка выглядит так (из руководства по вебхукам):

{
"id": "9d18457f-c71c-4be4-ae7c-ce04e48359ed",
"webhook_id": "9ced86a9-b8d9-4bc2-bbd8-5ffe5b456bc8",
"from": "TTd9qHyjqiUkfTxe3gotbuTMpjU8LEbpkN",
"to": "DScWVXehzWdV2YS8fA2ryNsiHpKiLgAxM",
"blocknumber": "65542464",
"type": "TRC20",
"contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
"txid": "18f52f2a55b94a6e3705de4abb18e95dfce79970f27b29450705c561e12b6988",
"amount": 108935
}

Как проверить подпись на сервере?

Пересчитайте HMAC от txid и сравните его с заголовком за постоянное время. Следующий обработчик Express делает именно это. Он читает секрет из переменной окружения, отклоняет отсутствующий или неверной длины заголовок и отвечает 200 только на действительные запросы:

const crypto = require('crypto');
const express = require('express');
const app = express();
app.use(express.json());
function isValid(txid, received, secret) {
const expected = crypto.createHmac('sha256', secret).update(txid).digest('base64');
const a = Buffer.from(expected);
const b = Buffer.from(received || '');
// timingSafeEqual throws when lengths differ, so check first
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
app.post('/hooks/deposit', (req, res) => {
const ok = isValid(req.body.txid, req.get('X-Signature'), process.env.CG_PERSONAL_SECRET);
if (!ok) return res.sendStatus(401);
// process req.body.txid, deduplicate on it, then acknowledge
res.sendStatus(200);
});
app.listen(3000);

В документации есть также версии на Python, Java и PHP. В Python для сравнения используйте hmac.compare_digest. В Node.js ту же задачу решает crypto.timingSafeEqual. Простое сравнение через == может раскрыть информацию о времени выполнения.

Как протестировать обработчик?

Вычислите подпись сами и отправьте поддельное уведомление на ваш локальный сервер. Команда openssl ниже создаёт тот же HMAC в Base64, который ожидает обработчик. Используйте тестовый секрет, никогда не настоящий:

Terminal window
TXID=18f52f2a55b94a6e3705de4abb18e95dfce79970f27b29450705c561e12b6988
SIG=$(printf '%s' "$TXID" | openssl dgst -sha256 -hmac "test-secret" -binary | base64)
curl -i -X POST http://localhost:3000/hooks/deposit \
-H "Content-Type: application/json" \
-H "X-Signature: $SIG" \
-d "{\"txid\": \"$TXID\"}"

Запустите сервер с CG_PERSONAL_SECRET=test-secret. Запрос вернёт 200. Измените один символ секрета или подписи, и вернётся 401. Повторяйте этот тест после каждого развёртывания обработчика и после перевыпуска настоящего секрета.

Что не покрывает подпись?

Она покрывает ID транзакции и ничего больше. По документированной конструкции в HMAC попадает только txid. Отсюда два следствия:

  • Действительная подпись доказывает, что Chaingateway отправил уведомление об этой транзакции. Она не доказывает, что amount, to или contractaddress в теле не изменены. Если от этих полей зависит выплата, сверьте их с сетью или с ожидаемыми значениями для заказа.
  • Одна и та же транзакция может прийти больше одного раза, например после того, как вы запросили повторную отправку неудачного уведомления, и каждая копия несёт одну и ту же действительную подпись. Дедуплицируйте по txid.

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

Как сменить секрет, не теряя уведомления?

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

  1. Разверните версию обработчика, которая сначала проверяет текущий секрет, а если проверка не прошла, пробует второй, необязательный CG_PERSONAL_SECRET_NEXT.
  2. Перевыпустите секрет в профиле и скопируйте новое значение.
  3. Поместите новое значение в CG_PERSONAL_SECRET_NEXT и разверните снова.
  4. Отправьте тестовый перевод в тестовой сети и убедитесь, что обработчик его принимает.
  5. Через сутки переведите новый секрет в CG_PERSONAL_SECRET и удалите старый.

Документация не говорит, каким секретом подписано уведомление, которое вы повторно отправляете после смены. Держите окно с двумя секретами открытым, пока список неудачных уведомлений не станет пустым.

Что происходит, если секрет не задан?

Тогда вебхуки отправляются без заголовка X-Signature. Ваш обработчик не должен считать отсутствие заголовка действительным. Решайте для каждой среды отдельно: в продакшене отклоняйте запросы без подписи, как только задали секрет, а в локальной тестовой среде их можно допускать. Заголовок также показывает, активен ли секрет: уведомление без него означает, что секрет в вашем аккаунте не задан.

Где полный справочник?

Руководство по безопасности вебхуков содержит шаги и код на четырёх языках, а руководство по вебхукам объясняет, как создавать вебхуки и принимающие конечные точки.

Как мы пишем эти статьи

Готовы собрать это сами? Получите свой API-ключ — 7-дневный пробный период, без карты — или посмотрите API блокчейна для полного справочника по эндпоинтам.

C
Chaingateway Team
Эксперты по блокчейну

Команда Chaingateway стремится упростить интеграцию блокчейна для разработчиков по всему миру.