Webhooks
The incoming Wallet Service webhook (TOPUP): how on-chain deposits arrive, the event body, signing, and processing.
V3 Custody receives on-chain deposit events from Wallet Service through a webhook. The webhook is called by Wallet Service, not by you; on the integration side, you consume the result (deposits, the activity feed, balances). For the end-to-end scenario, see the Handle an incoming deposit guide.
How an event is processed:
Incoming Wallet Service webhook
POST /webhooks/wallet (outside the /api/v1 prefix) accepts incoming on-chain events; currently only TOPUP is processed. The token is resolved from the registry by its contract address, the amount is credited to the recipient address, and a deposit record is created.
{
"tx": {
"network": "TRON",
"asset": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
"amount": "500.00",
"toAddress": "TQ5kohbBSdorGoDBmCGUmDL7RUvNr75mBC",
"txHash": "9f2c...e41a"
}
}
Field (tx) | Meaning |
|---|---|
network | network (TRON, …) |
asset | token contract address |
amount | deposit amount |
toAddress | recipient address |
txHash | transaction hash |
asset is the token's contract address. No strict body schema is enforced (it's an external contract, validated inside the handler), so the fields above are for illustration only. See the API Reference for the exact contract.
Signing and security
- In demo mode, the webhook is accepted without a signature or authentication.
- In production, HMAC verification is planned.
Until signing is introduced, restrict the request source at the network level (the trusted Wallet Service source).
Disabled tokens
If a token is disabled by the kill switch (enabled=false), the webhook ignores its events and the deposit isn't credited. Existing data and ledger accounts are left untouched.
What to read after a deposit
Once the deposit is credited, read the result:
| What you need | Request |
|---|---|
| deposit details | GET /api/v1/vaults/{code}/deposits/{id} |
| incoming in the feed | GET /api/v1/vaults/{code}/history?direction=in |
| balance | GET /api/v1/vaults/{code}/balances |
For the full flow, see the Handle an incoming deposit guide.
Outgoing webhooks
The current API has only the incoming Wallet Service webhook. Outgoing webhooks (for example, low Gas Station balance notifications) aren't available in the API yet.
Common mistakes
| Symptom | Cause |
|---|---|
webhook sent to /api/v1/... | it's outside the prefix, at /webhooks/wallet |
| deposit not credited | the token is disabled by the kill switch (enabled=false) or isn't in the registry |
| waiting for an outgoing webhook | there aren't any yet, only the incoming TOPUP |
| request rejected in production | HMAC is planned; for now, restrict the source at the network level |
handling events other than TOPUP | only TOPUP is currently supported |