Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Coin Webhook Events

When a deposit is credited or a send is processed on-chain, Roqqu notifies your configured webhook URL. The webhook body is encrypted; decrypt it with your API key. See Decrypt Webhook Body.

Payment link events are documented separately under Payment Link Webhook Events.

Webhook Event Types

  1. token_received — Triggered when a deposit to a merchant/customer wallet is credited

  2. token_sent — Triggered when an outbound send is processed on-chain

  3. token_refunded — Triggered when a failed send is refunded to the merchant balance

Buy / Sell / Swap

Buy, sell, and swap are ledger operations only. They do not emit webhook events. Use transaction history / balances to confirm those operations.

Fees are taken from the token used in the trade or send.

Webhook Payload Structure

All coin webhook events share the same top-level shape. The event_type and meta_data fields differ by event.

Field
Type
Description

event_id

string

Unique identifier for this webhook event

event_type

string

token_received, token_sent, or token_refunded

meta_data

object

Event-specific details (see below)

datetime

string

Timestamp of the related queue/deposit record


token_received (coin deposit)

meta_data fields

Field
Type
Description

address

string

Destination wallet address that received funds

extra

string | null

Extra/memo/tag when applicable

network

string

Network code to parse in requests (e.g. bitcoin, bep20, trc20)

token

string

Token symbol (e.g. btc, usdt)

value

number | string

Amount credited

hash

string

Blockchain transaction hash

status

string

Deposit credit status (e.g. confirmed)

customer

object | null

Customer object when the wallet was generated for a customer

address_total_received

number

Total received on that address (when available)

genesis

number

Genesis flag from the deposit record

Sample payload


token_sent (coin send)

meta_data fields

Field
Type
Description

destination

string

Destination address the tokens were sent to

extra

string | null

Extra/memo/tag when applicable

network

string

Network code to parse in requests (e.g. trc20)

token

string

Token symbol (e.g. usdt)

value

number | string

Amount sent

hash

string

Blockchain transaction hash

reference

string

Internal send reference ID (refid)

status

string

Processing status (e.g. processed)

Sample payload


token_refunded (send refund)

meta_data fields

Field
Type
Description

network

string

Network code to parse in requests

token

string

Token symbol

value

number | string

Amount refunded

hash

string

Hash recorded on the refund (e.g. admin_refund)

status

string

Refund status (e.g. confirmed)

refid

string

Original send reference ID

Sample payload

Important Notes

  • Webhooks are queued asynchronously and may have short delays

  • Always decrypt and verify the payload before acting on it

  • Configure which events you subscribe to when creating/updating your webhook URL

  • For payment link payments, use Payment Link Webhook Events instead of token_received

Last updated