Защита webhook криптоплатежей: подписи, повторное воспроизведение и доставка

Практическое руководство по защите webhook криптоплатежей: RSA-SHA256, точные подписанные байты, защита от повторов, надёжная идемпотентность и доставка.

Опубликовано , обновлено

Защита webhook криптоплатежей показана ноутбуком, замком и аккуратно свёрнутым кабелем на рабочем столе

Защита webhook криптоплатежей начинается с проверки подписанного запроса до доверия к нему, привязки платежа к сохранённому заказу и однократной записи его результатов. В Suawave проверяйте x-ca-signature с помощью RSA-SHA256, сохраняйте исходные подписанные байты и надёжно исключайте повторы UUID событий. Возвращайте HTTP 200 с *ok* только после принятия события в обработку с постоянным хранением.

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

1. Сохраните байты перед проверкой подписи

Публичные callback Suawave используют подпись RSA-SHA256 в base64 с дополнением PKCS#1 v1.5. Получите PKIX PUBLIC KEY PEM через GET /pubkey/ по HTTPS. Проверьте, что это RSA-ключ длиной не менее 2048 бит, и кешируйте его. Публичному верификатору не нужен общий секрет HMAC или доступ к закрытому ключу подписи.

Подписанное сообщение зависит от транспорта callback:

Транспорт callback Подписанное сообщение Частая ошибка интеграции
GET по умолчанию Полный внешний URL с исходным порядком query-параметров Сортировка или повторное кодирование параметров
Form POST с post=1 Точное исходное тело Разбор и повторное формирование формы
JSON POST с json=1 Точное исходное тело Повторная сериализация разобранного JSON

json=1 имеет приоритет над post=1. Эти параметры фиксируются первым вызовом create для пары тикер и callback. Повторный create с другими параметрами не перенастраивает существующий заказ. Выберите транспорт до создания адресов оплаты.

Для GET за прокси объединяйте настроенный доверенный внешний origin с исходным закодированным адресом запроса. Не доверяйте переданным клиентом заголовкам Host или forwarded-host при выборе origin. Для POST сохраняйте исходное тело до преобразований middleware JSON или формы. В документации проверки подписей указаны источники входных данных для разных фреймворков.

Короткий верификатор на Node.js

Эта функция взята из JavaScript-примера docs/site/examples/js/verify.js. Она проверяет подпись, но не является полным HTTP-обработчиком. Загружайте и проверяйте публичный ключ отдельно; передавайте исходный адрес запроса и Buffer с неизменённым телом POST.

const crypto = require('crypto');

function verifyCallback({ method, requestUri, rawBody, signature }, publicKeyPem, trustedOrigin) {
  let signed;
  if (method === 'GET') {
    signed = Buffer.from(trustedOrigin + requestUri, 'utf8');
  } else if (method === 'POST') {
    if (!Buffer.isBuffer(rawBody) || rawBody.length > 65536) return false;
    signed = rawBody;
  } else {
    return false;
  }
  if (!signature || !/^[A-Za-z0-9+/]+={0,2}$/.test(signature)) return false;
  const verifier = crypto.createVerify('RSA-SHA256');
  verifier.update(signed);
  return verifier.verify(publicKeyPem, signature, 'base64');
}

module.exports = { verifyCallback };

В Express передавайте req.originalUrl как requestUri и сохраняйте входные данные POST через express.raw до разбора. Также ограничьте размер запроса на уровне HTTP-обработчика. Там же перехватывайте исключения некорректного ключа и проверки, считая их отказом. Неудачная проверка должна приводить к HTTP 401 без изменения заказа.

Другие языки и подробности работы за прокси приведены в статье о проверке подписей callback с RSA-SHA256.

Проверяемое сообщение должно точно совпадать с подписанным: для GET это внешний origin и исходный адрес запроса, для POST это исходное тело. Suawave не передаёт временную метку callback, поэтому проверка подписи не устанавливает свежесть запроса.

2. Свяжите проверенный платёж с заказом

После проверки разберите запрос и найдите сохранённый заказ. Сравните его nonce и идентификатор, затем проверьте address_in и coin. Заказ с trc20/usdt ожидает trc20_usdt в поле coin callback. Не определяйте тикер по сумме или метке, которую передаёт покупатель.

POST подписывает тело, а ваши query-параметры callback остаются в URL. Подпись не делает произвольный идентификатор заказа в query-параметрах достоверным. Сопоставление проверенного адреса приёма и coin с сохранённым заказом не позволяет приписать подлинное тело чужому заказу.

Создавайте новый непредсказуемый nonce для callback URL каждого заказа и сохраняйте полный исходный URL на сервере. Он также даёт доступ к публичным журналам, поэтому исключите его из аналитики и видимых покупателю ссылок. Nonce помогает привязать заказ, но не делает перехваченное подписанное событие свежим.

Проверьте pending до учёта средств. Подлинное pending-событие ещё не даёт основания выполнять заказ. Для confirmed-события по-прежнему нужна проверка суммы. Статья о недоплате криптовалютой разбирает суммы до комиссий, чистые суммы и отдельные поступления.

3. Предотвращайте повторную обработку с помощью надёжной идемпотентности

У публичных callback Suawave нет временной метки и ID ключа. Не вводите проверку «не старше пяти минут» по заголовку, который шлюз не отправляет. Перехваченный запрос может оставаться криптографически корректным. Ваша защита состоит в том, чтобы его повторная обработка не имела дополнительных последствий.

Сохраняйте UUID каждого обработанного события в той же транзакции базы данных, что и запись платежа и переход состояния заказа. Создайте ограничение уникальности UUID. Предварительный запрос «существует ли запись?» без этого ограничения допускает гонку при одновременном поступлении двух запросов.

Подходящая последовательность транзакции:

  1. Вставьте UUID проверенного события, считая конфликт уникальности признаком уже принятого события.
  2. Заблокируйте соответствующий заказ и при необходимости запишите подтверждённую сумму поступления.
  3. Применяйте только переходы заказа вперёд и надёжно сохраняйте задания на его выполнение.
  4. Зафиксируйте транзакцию до отправки подтверждения получения.

Если транзакция завершается ошибкой, не подтверждайте успех. Повторная доставка позволит выполнить работу снова. Если транзакция зафиксирована, но соединение обрывается до получения ответа, повторный запрос находит сохранённый UUID и подтверждает получение без повторного изменения заказа.

Достаточно ли исключать повторные UUID, чтобы не отправить товар дважды?

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

Pending и confirmed callback одного поступления имеют разные UUID. Помимо записей событий храните состояние поступления и не позволяйте позднему pending-событию отменить подтверждение. Статья о финальности криптоплатежей объясняет смысл обоих типов callback.

Повторные доставки одного события проходят через один UUID и одно зафиксированное действие заказа. Ответ HTTP 200 следует за фиксацией; при повторе сохранённый UUID позволяет подтвердить получение без второго действия.

4. Правильно подтверждайте получение и учитывайте повторные попытки

Suawave ожидает HTTP 200 с обычным текстом *ok* в течение 30 секунд. Обычное ok тоже принимается без учёта регистра. Последовательно используйте документированный ответ *ok*, чтобы поведение фреймворка по умолчанию не превращало принятое событие в новую попытку доставки.

HTTP 204, JSON-объект об успехе или перенаправление не являются таким подтверждением. Переход по перенаправлениям не выполняется. Настройте непосредственно конечный HTTPS-путь callback с точным написанием, которое требует приложение.

Предусмотрено восемь попыток доставки. После первой отправки задержки составляют 30 секунд, 2 минуты, 10 минут, 30 минут, 2 часа, 6 часов и 24 часа, каждая с добавлением случайного отклонения до 10 процентов. UUID остаётся прежним. Это последовательные задержки повторных попыток, а не обещание доставки в точное время.

Вынесите медленную работу за пределы запроса. Постоянное хранение события и задания выполнения позволяет подтвердить получение, пока упаковка, отправка письма или предоставление доступа выполняются отдельно. Очередь только в памяти не гарантирует надёжного принятия: процесс может завершиться после подтверждения и потерять задание.

Руководство по callback описывает подтверждение получения, порядок и повторные попытки. Считайте уже обработанное корректное событие обычным успехом, чтобы шлюз прекратил повторную доставку.

5. Обрабатывайте ротацию ключей без принятия произвольных ключей

Кешируйте ключ с настроенного эндпоинта Suawave. При неудачной проверке один раз обновите этот ключ и повторите проверку перед отклонением запроса. Ротация переводит на новый ключ подписи и повторные доставки старых событий; UUID события по-прежнему служит идентификатором для исключения дублей.

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

В эксплуатационных журналах разделяйте неверные подписи и корректные события, которые не удалось зафиксировать. Первое указывает на изменённые подписанные байты или недоверенный запрос, второе на сбой обработки. В обоих случаях избегайте записи полных callback URL, содержащих секреты.

6. Сверяйте пропущенные callback и проверяйте сценарии отказа

Для расследования пропусков доставки используйте GET /{ticker}/logs/ с исходным callback URL. Результат sent означает, что перевод подтверждён, но получение его confirmed callback не подтверждено, в том числе после исчерпания повторных попыток. done означает, что получение confirmed callback подтверждено. Журналы служат резервным способом сверки; обычный путь приёма по-прежнему основан на проверенных callback.

Перед выпуском дважды отправьте одно подлинное подписанное событие через обработчик и убедитесь, что существует только одно постоянно сохранённое действие. Измените один подписанный байт и требуйте отклонения. Проверьте сбой базы данных до фиксации и потерю подтверждения получения после неё. Доставьте confirmed-событие раньше pending и убедитесь, что заказ остаётся оплаченным.

Наконец, проверьте привязку суммы и сети на двух отдельных заказах. Корректная подпись одного поступления не должна оплачивать другой заказ. Руководство по интеграции USDT показывает, как хранить эти данные заказа, а статья «USDT TRC20 и BEP20» объясняет, почему сеть должна храниться рядом с суммой в каждой записи оплаты.