Перейти к содержанию

🔔 Callback уведомления

При изменении статуса заявки система отправляет HTTP POST запрос на указанный webhook_url.

  • Формат тела: JSON
  • Метод: POST
  • Возможны повторные отправки
  • Поддерживается Static (Bearer) и Dynamic (HMAC) проверка подлинности
  • Bearer-токен и HMAC-заголовки могут приходить одновременно

Важно: КБ токен обновляется только в личном кабинете в разделе токены, выводится только один раз вместе с шаблоном шифрования. Тоже самое касается статичных токенов для апи, они обновляются в личном кабинете и выводятся один раз, поэтому обязательно нужно сохранять к себе

🔐 Проверка подлинности

Поддерживаются два способа верификации запроса.

1️⃣ Static (Bearer-токен)

В заголовке запроса передаётся токен:

Text Only
1
2
Content-Type: application/json
Authorization: Bearer <callback_token>

Мерчанту необходимо сравнить значение Authorization с токеном, полученном в личном кабинете

2️⃣ Dynamic (HMAC-подпись)

Используется HMAC SHA256 подпись.

Заголовки (Dynamic)

Text Only
1
2
3
4
Content-Type: application/json
X-Signature-Method: dynamic
X-Timestamp: <unix_timestamp>
X-Signature: <hmac_sha256>

Дополнительно могут присутствовать служебные заголовки:

Text Only
1
2
3
X-Real-Ip
X-Forwarded-Url
User-Agent

Шаблон подписи (signature_string)

Шаблон строки для подписи выводится при обновлении Кб токена

ВАЖНО: КБ токен обновляется только в личном кабинете в разделе токены, выводится только один раз вместе с шаблоном шифрования.

Пример шаблона:

Text Only
1
{id}:{status}:{amount}:{timestamp}

На основе шаблона формируется строка для подписи (signature_string).

⚠️ Фактическая строка может отличаться — всегда используйте шаблон, указанный в ЛК.

Пример текущей строки для подписи

Text Only
1
{id}:{status}
Пример
Text Only
1
10441030:failed

Формирование подписи

Text Only
1
HMAC_SHA256(secret_key, signature_string)

Где: - secret_key — секретный ключ из личного кабинета - signature_string — строка, собранная по шаблону

Полученное значение необходимо сравнить с заголовком X-Signature.

📦 Пример Callback запроса (Dynamic)

Headers (реальный пример)

Text Only
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
x-timestamp: 1770215066
x-signature-method: dynamic
x-signature: e073100fe06bd4eb4e43067c4a8bfaccd96bbbac5612ff9dfaf765c7e126fa7d
authorization: Bearer 5fvQBy-dLFlTRw4rXfmNlQj14iob96uhdGqEbF8poPw
content-type: application/json
x-real-ip: 1234
x-forwarded-url:
accept-encoding: gzip, deflate
accept: */*
content-length: 534
user-agent: python-requests/2.31.0
host: webhook.site

Body

JSON
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "id": 10441030,
  "status": "failed",
  "amount": 5431.0,
  "method": "to_sbp_number",
  "outter_id": null,
  "form_outter_id": null,
  "reject_reason": null,
  "geo": "Россия",
  "merchant_detail": {
    "amount": 5431.0,
    "amount_in_usdt": 69.9871,
    "rate": 11.0,
    "course": 77.6
  },
  "sum": 5431.0,
  "merchant": "TestMerchLK",
  "created_at": "2026-02-04T10:47:56.991106+00:00",
  "updated_at": "2026-02-04T14:14:55.639651+00:00",
  "X-Request-Id": "f80c80bb-da98-4690-a35c-4c4219292731",
  "callback_attempt_id": "10441030_1770214495"
}

📘 Поля в теле Callback

Поле Тип Описание
id integer ID заявки в системе
status string Статус заявки (success, failed)
amount number Сумма заявки
sum number Сумма заявки
method string Способ перевода
outter_id string / null Внешний ID заявки
form_outter_id string / null Внешний ID формы
reject_reason string / null Причина отказа
geo string Гео
merchant string Имя мерчанта
merchant_detail object Детализация (курс / комиссия)
created_at string Дата создания заявки
updated_at string Дата последнего изменения
X-Request-Id string Уникальный ID запроса
callback_attempt_id string ID попытки отправки коллбека

🧾 Что должен делать мерчант

  1. Проверить подлинность запроса

  2. Static — сверить Bearer-токен

  3. Dynamic — пересчитать HMAC по шаблону из ЛК и сверить X-Signature

  4. Обработать статус заявки

  5. По id и/или outter_id

  6. Сделать обработку идемпотентной

  7. Повторные коллбеки возможны

✅ Ответ на Callback

Если обработка прошла успешно — верните:

Text Only
1
HTTP 200

или любой другой 2xx статус.

Любой ответ 4xx / 5xx считается ошибкой — коллбек будет отправлен повторно.

🔁 Повторные отправки

В случае ошибки система выполняет повторные попытки с задержкой.

Рекомендуется:

  • обрабатывать запросы идемпотентно
  • использовать id или callback_attempt_id для защиты от дублей