Webhooks

Основные сведения

Когда пользователь оплачивает ваш заказ, мы отправляем вам веб-хук с уведомлением о том, что заказ был успешно оплачен. Вы должны проверить и подтвердить получение информации о заказе.

Для валидации подписи входящих запросов необходимо получить секретный ключ. Секретный ключ доступен в личном кабинете в разделе «Ключи API».

Обработка ответа на вебхук

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

Сервер должен возвращать HTTP-статус 200 и передавать в теле ответа строку «OK».

Как расшифровать и проверить оригинал

Данные закодированы в base64:

{
  "data": "eyJpZCI6ImI4NjY3NTUwLWM4MmUtNDA0Yi04ZTY0LTc0Zjk4NGM2ZmRkMyIsInR5cGUiOiJvcmRlci5wYXJ0aWFsX2NvbXBsZXRlIiwiY3VzdG9tZXJfZW1haWwiOiJpZDEwMkB0YWRib3guY29tIiwib3JkZXJfaWQiOiJ0WDlPSDVVZ2t6Q1NYT3FOODdyRSIsInRvdGFsX2Ftb3VudCI6MiwiY3VycmVuY3lfY29kZSI6IkVVUiIsInBheW1lbnRfc3RhdHVzIjoiQUNDRVBURURfU0VUVExFTUVOVF9JTl9QUk9DRVNTIn0=",
  "sign": "1X+hFWMfdyAWbtcPTlhGG5cnLJVTyjB0jgXBT8sFDXA=",
  "callbackUrl": "https://webhook.site/b972cd25-8118-465b-bdd0-d4c20bb897c7"
}

Поле sign — это цифровая подпись, которая подтверждает:

• данные не изменялись

• запрос действительно пришёл от отправителя

Общая логика проверки

1. Возьмите значение поля data из запроса в формате Base64 (не декодируя).

2. Используйте секретный ключ, полученный в личном кабинете.

3. Сгенерируйте подпись по алгоритму HMAC-SHA256:

   • Исходные данные: значение поля data в Base64

   • Ключ: секретный ключ

4. Закодируйте результат HMAC в Base64.

5. Сравните полученную подпись с полем sign из запроса.

Если подписи совпадают, запрос считается подлинным и не изменённым.

Пример на JavaScript (Node.js)

import crypto from 'crypto';

const secretKey = 'SECRET_KEY';

const data =
  'eyJpZCI6ImI4NjY3NTUwLWM4MmUtNDA0Yi04ZTY0LTc0Zjk4NGM2ZmRkMyIsInR5cGUiOiJvcmRlci5wYXJ0aWFsX2NvbXBsZXRlIiwiY3VzdG9tZXJfZW1haWwiOiJpZDEwMkB0YWRib3guY29tIiwib3JkZXJfaWQiOiJ0WDlPSDVVZ2t6Q1NYT3FOODdyRSIsInRvdGFsX2Ftb3VudCI6MiwiY3VycmVuY3lfY29kZSI6IkVVUiIsInBheW1lbnRfc3RhdHVzIjoiQUNDRVBURURfU0VUVExFTUVOVF9JTl9QUk9DRVNTIn0=';

const expectedSign =
  '1X+hFWMfdyAWbtcPTlhGG5cnLJVTyjB0jgXBT8sFDXA=';

const calculatedSign = crypto
  .createHmac('sha256', secretKey)
  .update(data)
  .digest('base64');

console.log(calculatedSign === expectedSign); // true / false

В результате расшифровки вебхука содержатся следующие данные:

{
	"id":"b8667550-c82e-404b-8e64-74f984c6fdd3",
	"customer_email":"[email protected]",
	"order_id":"tX9OH5UgkzCSXOqN87rE",
	"total_amount":2,
	"currency_code":"EUR",
	"payment_status":"ACCEPTED_SETTLEMENT_IN_PROCESS" //Статус транзакции. Возможные значения:"ACCEPTED_SETTLEMENT_IN_PROCESS", "COMPLETED", "CANCELED"
}