Вебхуки

Что такое вебхуки

Вебхук — это механизм автоматических уведомлений: вы один раз указываете URL своего сервера, и RusWallet сам присылает на него POST-запрос каждый раз, когда по заявке происходит значимое событие — например, меняется её статус. Благодаря этому вам не нужно постоянно опрашивать API (polling): в момент, когда заявка переходит в статус «Одобрено» или «Отклонено», актуальные данные приходят к вам сразу.

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

Где настроить

1. Откройте личный кабинет партнёра → раздел «API доступы».
2. В блоке «Настройка вебхука» укажите URL вашего обработчика (http:// или https://) и сохраните.
3. Там же скопируйте секретные ключи (api_secret) для Sandbox и Live — они нужны для проверки подписи.
4. Проверьте интеграцию кнопкой «Тестовое событие» на странице «Логи вебхуков».

Указывается один URL — на него приходят и тестовые (Sandbox), и боевые (Live) события. Различить среду можно по полю sandbox в теле запроса (см. ниже).

Структура запроса

RusWallet отправляет POST со следующими заголовками:

POST /ваш-webhook-url HTTP/1.1
Content-Type: application/json
X-RusWallet-Signature: sha256=<hmac>
X-RusWallet-Timestamp: 2026-06-15T12:34:56+00:00

Тело запроса (пример события об изменении статуса):

{
  "event": "application.status_changed",
  "application_id": "550e8400-e29b-41d4-a716-446655440000",
  "order_id": "SHOP-12345",
  "status": "contract",
  "previous_status": "scoring",
  "sandbox": false,
  "timestamp": "2026-06-15T12:34:56+00:00",
  "details": {
    "broker": "FinBox",
    "form_url": "https://...",
    "partner_access_url": "https://...",
    "contract_number": "FC-2026-001",
    "credit_limit": 100000,
    "monthly_payment": 8500
  }
}

Поле order_id — это ваш идентификатор заказа, переданный при создании заявки. Блок details может быть null, если по заявке ещё нет ответа от брокера. Ваш обработчик должен вернуть HTTP-код 2xx — иначе доставка будет повторена (см. «Повторные попытки»).

Проверка подписи

Подпись формируется по алгоритму HMAC-SHA256: ключом служит ваш api_secret, а подписываемая строка — это timestamp, точка и тело запроса (timestamp + "." + тело). Берите тело ответа от сервера в том виде, в каком оно пришло, — не разбирайте и не собирайте JSON заново, иначе подпись не совпадёт. Например, если вы используете PHP, то можно сделать так:

$payload   = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_RUSWALLET_TIMESTAMP'] ?? '';
$received  = $_SERVER['HTTP_X_RUSWALLET_SIGNATURE'] ?? '';

$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $payload, $apiSecret);

if (! hash_equals($expected, $received)) {
    http_response_code(401);
    exit('invalid signature');
}

// Подпись верна — обрабатываем событие
$event = json_decode($payload, true);

Какой секрет использовать, зависит от среды: для боевых событий — api_secret среды Live, для тестовых — api_secret среды Sandbox. Оба ключа доступны в разделе «API доступы».

Статусы заявки

Поле status содержит агрегированный статус заявки. Жизненный цикл: created → processing → scoring → contract → end, с возможными ответвлениями decline, cancel, for_refund.

Sandbox и Live

На один и тот же webhook URL приходят события обеих сред. Отличить их можно только по полю sandbox в теле запроса (true — тестовое событие, false — боевое). Отдельного заголовка среды нет.

При этом подпись тестовых и боевых событий считается разными секретами (api_secret Sandbox против Live), поэтому проверять подпись нужно соответствующим ключом в зависимости от значения sandbox.

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

Если ваш сервер ответил кодом, отличным от 2xx, или не ответил вовсе, RusWallet повторит доставку. Всего до 5 попыток с нарастающими паузами:

попытка 1 → ошибка → пауза 30 сек
попытка 2 → ошибка → пауза 2 мин
попытка 3 → ошибка → пауза 10 мин
попытка 4 → ошибка → пауза 1 час
попытка 5 → ошибка → доставка прекращается

Все попытки доставки видны в личном кабинете в разделе «Логи вебхуков» — там можно посмотреть отправленные заголовки, тело и ответ вашего сервера. Как страховку на случай пропущенных уведомлений используйте опрос статуса: GET https://ruswallet.ru/api/v1/applications/{uuid}.

Тестовое событие

Кнопка «Тестовое событие» на странице «Логи вебхуков» отправляет на ваш URL случайное тестовое уведомление (всегда Sandbox). У таких событий:

• тип "event": "test.ping" (вместо application.status_changed);
• дополнительный заголовок X-RusWallet-Test: true;
• поле sandbox равно true, а application_id и order_id — случайные тестовые значения.

{
  "event": "test.ping",
  "application_id": "550e8400-e29b-41d4-a716-446655440001",
  "order_id": "TEST-ABCD1234",
  "status": "processing",
  "previous_status": null,
  "sandbox": true,
  "timestamp": "2026-06-15T12:34:57+00:00",
  "details": {
    "broker": "Sandbox (Mock)",
    "message": "Это тестовое событие от RusWallet для проверки вашего вебхука."
  }
}