Проверка подписи webhook: HMAC-SHA256 без ошибок

Короткий ответ и границы сценария

Правильная строка подписи собирается из X-Timestamp, точки и неизменённого raw body; повторная сериализация JSON почти всегда даст другой HMAC. Материал рассчитан на разработчика, который принимает серверные события RollyPay. Сначала определите бизнес-объект, который изменится после оплаты: заказ, бронь, период доступа, лицензия или обязательство перед клиентом.

Сервер получает тело с пробелами в JSON. Если сначала распарсить объект и сериализовать снова, порядок и формат изменятся. Поэтому HMAC считается по исходным байтам, а JSON разбирается только после успешного сравнения. Это конкретный пример модели, а не универсальное разрешение для любой категории. Условия подключения, способы оплаты и документы подтверждаются для проекта во время модерации.

Интеграция платежей — это протокол состояний, а не один HTTP-запрос. Сервер проекта создаёт платёж, сохраняет payment_id и pay_url, отдаёт ссылку клиенту, принимает подписанные события и идемпотентно меняет заказ. Каждый переход должен быть наблюдаемым и повторяемым.

Как выбрать рабочий вариант

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

Шесть точек, которые определяют результат

исходные байты

Контрольная точка «исходные байты» задаёт исходные данные для материала «Проверка подписи webhook: HMAC-SHA256 без ошибок». Зафиксируйте решение в карточке заказа до создания платежа, чтобы повторный запрос не создавал новую продажу случайно.

метка времени

Пункт «метка времени» должен быть понятен покупателю до перехода в форму: покажите сумму, назначение и ожидаемый результат. Интерфейс отдельно объясняет ожидание, успех, отмену и истечение, не подменяя серверный статус красивым экраном.

точка-разделитель

Для пункта «точка-разделитель» определите техническое доказательство завершения: проверенное событие, совпавшие сумма и валюта, известные order_id и payment_id. Только после этой проверки запускайте продуктовую выдачу или исполнение заказа.

signing secret

У элемента «signing secret» должен быть владелец исключений. Ему нужна история попыток и правило, которое объясняет, можно ли безопасно повторить создание, отправку ссылки или выдачу без доступа к API-ключам.

constant-time сравнение

Требование «constant-time сравнение» проверьте повторной доставкой callback. Два одинаковых события не должны дважды продлевать доступ, резервировать место, начислять баланс или отправлять товар; ограничение фиксируют на уровне данных.

окно свежести

Для точки «окно свежести» заранее опишите возврат, спор и задержку результата. Покупателю нужен понятный канал поддержки, а команде — связь между исходным заказом, платежом, документом и обратной операцией.

Пошаговая схема

1. исходные байты. Ограничьте таймаут исходящего запроса и логируйте trace-id без ключей и персональных данных. Запишите входные данные, ответственного и условие завершения. Если нужен денежный результат, сообщение пользователя и визуальный редирект не заменяют проверенный серверный статус.
2. метка времени. Генерируйте уникальный X-Nonce для каждой попытки, но сохраняйте order_id при безопасном повторе создания. Запишите входные данные, ответственного и условие завершения. Если нужен денежный результат, сообщение пользователя и визуальный редирект не заменяют проверенный серверный статус.
3. точка-разделитель. Сохраняйте raw body webhook до проверки подписи и сравнивайте HMAC в constant-time режиме. Запишите входные данные, ответственного и условие завершения. Если нужен денежный результат, сообщение пользователя и визуальный редирект не заменяют проверенный серверный статус.
4. signing secret. Обрабатывайте payment.paid, payment.canceled и payment.expired как явные состояния. Запишите входные данные, ответственного и условие завершения. Если нужен денежный результат, сообщение пользователя и визуальный редирект не заменяют проверенный серверный статус.
5. constant-time сравнение. Проверяйте интеграцию тестовыми сценариями, включая повтор события и недоступность вашего callback URL. Запишите входные данные, ответственного и условие завершения. Если нужен денежный результат, сообщение пользователя и визуальный редирект не заменяют проверенный серверный статус.

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

Как собрать сценарий на RollyPay

Backend создаёт платёж методом POST /api/v1/payments. Для задачи «проверка подписи webhook HMAC-SHA256» он передаёт X-API-Key, новый X-Nonce и стабильный order_id, связанный с пунктом «исходные байты». В ответ сохраняются payment_id и pay_url.

Результат приходит на callback_url. До JSON-разбора сервер проверяет X-Signature как HMAC-SHA256 от X-Timestamp + "." + raw body, затем сверяет сумму, валюту, order_id и ожидаемый переход «точка-разделитель».

Выдача по payment.paid защищается уникальным ключом, связанным с «constant-time сравнение». payment.canceled и payment.expired закрывают попытку, но не стирают историю; повтор события заканчивается тем же итогом без повторного побочного эффекта.

Для темы «Проверка подписи webhook: HMAC-SHA256 без ошибок» условия и варианты подключения собраны на странице решения RollyPay. Там можно сопоставить сценарий с продуктом, а здесь сохранить инструкцию и контрольные детали для реализации.

Пример для интеграции

Фрагмент показывает только ключевой принцип. Добавьте типизацию ответа, таймауты, безопасное хранение секретов, журналирование без чувствительных данных и обработку всех HTTP-статусов.

const signed = timestamp + "." + rawBody;
const expected = crypto.createHmac("sha256", signingSecret).update(signed).digest("hex");
const valid = expected.length === signature.length &&
  crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
if (!valid) return response.status(403).send("Invalid signature");

Частые ошибки

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

Интерфейс принят за доказательство. Пункт «метка времени» может быть кнопкой, QR, ссылкой или экраном возврата. Денежный результат всё равно подтверждают серверное состояние и проверенное событие.

Разорваны данные процесса. Пункты «точка-разделитель» и «constant-time сравнение» должны быть связаны через order_id, payment_id, сумму, валюту и последнее событие. Тогда повтор или позднее подтверждение обрабатываются безопасно.

Нет владельца исключений. Пункт «окно свежести» включает возврат, истечение, спор и сбой доставки. Для каждого случая нужны статус, ответственная роль и понятное сообщение покупателю.

Что проверить до публикации

Для server-to-server запросов RollyPay используется X-API-Key, а X-Nonce защищает от повтора одного запроса. Уникальный order_id является естественным ключом идемпотентности создания платежа. Секреты хранятся только на backend и не попадают в браузер, мобильный клиент или репозиторий.

Webhook подписывается HMAC-SHA256 по строке X-Timestamp, точка и исходное тело запроса. Проверка выполняется до JSON-разбора; после неё обработчик сверяет событие, сумму, валюту и заказ, фиксирует event/payment_id и отвечает 2xx только после надёжного сохранения результата.

• Категория проекта и предмет продажи описаны одинаково на сайте, в боте и в заявке на подключение.
• Цена, валюта, срок действия предложения и правила возврата видны до оплаты.
• Секреты находятся только на сервере, а журнал не содержит API-ключей и полного тела с чувствительными данными.
• Успех, отмена, истечение, повтор события и недоступность callback проверены до реальных продаж.
• Налоговый или кассовый документ создаётся по правилам статуса продавца и связан с заказом.