Webhook-уведомления

Общая информация

Webhook — это механизм асинхронных уведомлений, с помощью которого наша платформа отправляет события на ваш сервер в режиме реального времени.
Уведомления отправляются на указанный вами URL при изменении состояния платежей и при возникновении системных событий.

Без настроенного webhook вы не сможете своевременно получать информацию о ходе обработки транзакций.

Какие события передаются через webhook

На указанный endpoint могут поступать уведомления о следующих событиях:

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

Настройка webhook-адреса

Адрес для получения webhook-уведомлений можно задать одним из способов:

Через личный кабинет мерчанта
URL указывается вручную на странице настроек интеграции.
Через API
Адрес может быть задан программно с использованием API, что удобно при динамической настройке окружений.

После сохранения настроек система автоматически начнёт отправлять уведомления при каждом изменении состояния транзакций.

Если webhook-адрес не указан, уведомления отправляться не будут.

Требования к webhook-endpoint

Webhook URL должен соответствовать следующим требованиям:

быть публично доступным по HTTPS;
корректно принимать POST-запросы;
возвращать HTTP-код 200 OK после успешной обработки;
обрабатывать повторные запросы (возможны ретраи).

Безопасность webhook

Каждый webhook-запрос подписывается.
Подпись передаётся в HTTP-заголовке x-signature.

Перед обработкой webhook обязательно реализуйте механизм проверки подписи, описанный в разделе
Аутентификация и подпись.

Webhook без валидной подписи не должен обрабатываться.

Пример HTTP-запроса webhook

POST /webhook
Host: yourdomain.com
Content-Type: application/json
x-signature: d3b07384d113edec49eaa6238ad5ff00

Пример тела webhook-уведомления

{
    "id": "45450d2a-e352-439d-9886-134f27c54750",
    "merchantTransactionId": "1254453",
    "amount": "5000.00",
    "crypto": "61865875",
    "rate": "80.82",
    "fee": "4330612",
    "type": "pay-in",
    "method": "c2c",
    "status": "active",
    "requisite": {
        "id": "8d920c8f-ca6d-4a69-ada0-fe7f43db286c",
        "bank": "ATB",
        "link": null,
        "currency": "RUB",
        "ownerName": "qweqwe",
        "sbpNumber": null,
        "cardNumber": "2323232323232",
        "accountNumber": null,
        "bankBic": null
    },
    "paymentPageUrl": null,
    "dispute": {
        "disputeCreatedAt": null,
        "disputeMerchantCheckUrl": null,
        "disputeTraderCheckUrl": null,
        "disputeTraderFiatAmount": "0.00",
        "disputeTraderDeclineReason": null,
        "cancelReason": "NONE"
    },
    "payerInfo": {},
    "transactionWindowInMin": 15,
    "createdAt": "2026-01-15T20:41:08.822Z",
    "invoicesUrl": null,
    "merchantId": "befbd03c-3c62-42c8-9292-9074abcf7500",
    "callbackUrl": null
}

Основные поля уведомления

id — уникальный идентификатор транзакции;
amount — сумма в фиатной валюте;
crypto — сумма в криптовалюте;
fee — комиссия мерчанта;
status — текущий статус операции;
type — тип транзакции (например, pay-in);
requisite — реквизиты, используемые для проведения платежа;
createdAt — дата и время создания транзакции.

Полный список возможных статусов описан в разделе Статусы транзакций.

Важные замечания

Webhook следует обрабатывать идемпотентно
Подпись должна проверяться до любой бизнес-логики
Невалидные или неподписанные запросы необходимо отклонять
При ошибке обработки допускается повторная отправка уведомления

Корректная настройка webhook является обязательным этапом интеграции и обеспечивает получение актуальной информации о состоянии платежей.