Вебхуки
Входящий вебхук Wallet Service (TOPUP) — как приходят on-chain поступления, тело события, подпись и обработка.
V3 Custody получает on-chain события о поступлениях от Wallet Service через вебхук. Вебхук вызывает Wallet Service, а не вы; со стороны интеграции вы потребляете результат (депозиты, лента, баланс). Прикладной сценарий — в гайде Обработать входящее поступление.
Входящий вебхук Wallet Service
POST /webhooks/wallet (вне префикса /api/v1) принимает входящие on-chain события; сейчас обрабатывается только TOPUP. Токен резолвится из реестра по contract address, сумма зачисляется на адрес-получатель, и создаётся запись депозита.
{
"tx": {
"network": "TRON",
"asset": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
"amount": "500.00",
"toAddress": "TQ5kohbBSdorGoDBmCGUmDL7RUvNr75mBC",
"txHash": "9f2c...e41a"
}
}
asset — это contract address токена. Строгая схема тела не навязывается (внешний контракт, валидация внутри handler'а), поэтому поля приведены для примера — точный контракт смотрите в Справочнике API.
Подпись и безопасность
- В демо-режиме вебхук принимается без подписи и аутентификации.
- В проде планируется проверка HMAC — [TODO: описать схему HMAC-подписи и заголовок, когда она появится].
Пока подпись не введена, ограничивайте источник запросов на сетевом уровне (доверенный источник Wallet Service).
Отключённые токены
Если токен отключён kill-switch'ом (enabled=false), вебхук игнорирует события по нему: депозит не зачисляется. Существующие данные и ledger-счета при этом не трогаются.
Что читать после поступления
После зачисления читайте результат: детали депозита (GET /vaults/{code}/deposits/{id}), ленту (GET /vaults/{code}/history?direction=in) и балансы. Подробный флоу — в гайде Обработать входящее поступление.
Исходящие вебхуки
В текущем API есть только входящий вебхук Wallet Service. Исходящих вебхуков (например, уведомлений о низком балансе Gas Station) в API пока нет — [TODO: описать исходящие вебхуки, когда они появятся].