Webhooks

Finance OS отправляет webhooks для событий, которые требуют асинхронной обработки на стороне клиента: входящие крипто-депозиты, изменения статуса вывода, KYC-вердикты, исполнение торговых ордеров. Также Finance OS обрабатывает входящие события от своих платёжных и compliance-провайдеров — это внутренняя интеграция, на которую вы как клиент API не подписываетесь.

Регистрация webhook URL

В Личном Кабинете: fin-os.io/cabinet/api-tokens → раздел «Webhooks» → добавить URL. Endpoint должен:

Принимать POST с JSON-телом.
Возвращать 2xx в течение 10 секунд.
Быть на HTTPS (HTTP отклоняется).

Формат payload

{
  "id": "evt_5f8d7a3c-1234-4567-89ab-cdef01234567",
  "type": "wallet.deposit.confirmed",
  "created_at": "2026-05-27T14:23:00Z",
  "data": {
    "transaction_id": "tx_8e23f...",
    "wallet_id": "wlt_9c12d...",
    "amount": "100.000000",
    "currency": "USDT",
    "network": "TRC20",
    "tx_hash": "0xabc..."
  }
}

Структура event

Name	Type	Required	Description
`id`	`string (uuid)`	optional	Уникальный ID события. Используйте для idempotency на вашей стороне.
`type`	`string`	optional	Тип события (см. список ниже).
`created_at`	`timestamp`	optional	Когда событие произошло на платформе.
`data`	`object`	optional	Payload, специфичный для типа события.

Поддерживаемые события

Name	Required	Description
`wallet.deposit.detected`	optional	Крипто-депозит обнаружен в mempool (0 подтверждений).
`wallet.deposit.confirmed`	optional	Депозит подтверждён (TRC20: 1 conf, BTC: 2 conf).
`wallet.withdraw.pending`	optional	Вывод отправлен в сеть, ждём подтверждения.
`wallet.withdraw.completed`	optional	Вывод подтверждён в сети.
`wallet.withdraw.failed`	optional	Вывод отвергнут (compliance/network).
`kyc.approved`	optional	KYC-верификация пройдена.
`kyc.rejected`	optional	KYC отклонён. Причина в `data.reason`.
`trading.order.filled`	optional	Торговый ордер исполнен.
`trading.order.cancelled`	optional	Торговый ордер отменён.
`otc.deal.completed`	optional	OTC-сделка завершена (обе стороны подписали).
`otc.deal.disputed`	optional	OTC-сделка передана в арбитраж.

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

Каждый webhook содержит заголовок X-FinOs-Signature — HMAC-SHA256 от raw body, с ключом, который вы получаете при регистрации webhook URL в ЛК.

⊘

Всегда проверяйте подпись

Без проверки подписи злоумышленник может отправить вам поддельный webhook (например, «деньги пришли») и спровоцировать выдачу товара. Сравнение должно быть constant-time (hash_equals в PHP, crypto.timingSafeEqual в Node).

Retry политика

Если ваш endpoint вернул не-2xx или превысил 10s таймаут, Finance OS повторит доставку:

1-я повторная попытка — через 30 секунд
2-я — через 5 минут
3-я — через 30 минут
4-я — через 6 часов
5-я — через 24 часа

После 5 неуспешных попыток событие помечается как failed и письмо уходит на email владельца аккаунта. Историю всех попыток можно посмотреть в ЛК в разделе «Webhooks → Logs».

Идемпотентная обработка

Каждое событие имеет уникальный id. Сохраняйте обработанные ID в БД и игнорируйте повторы — это защитит от double-processing при retry.

Внутренние входящие webhooks

Finance OS также принимает события от своих back-end интеграций (платёжный шлюз, провайдер верификации, торговый bridge). Эти эндпоинты внутренние — внешние интеграторы их не используют.

Эти эндпоинты обслуживают входящий трафик от платёжного шлюза (события по СБП-операциям и крипто-операциям), от верификационного провайдера (вердикты KYC) и от движка алгоритмического трейдинга. Они закрыты HMAC-подписью провайдера и недоступны для внешних вызовов.