> For the complete documentation index, see [llms.txt](https://roqqu-api-services.gitbook.io/ras/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://roqqu-api-services.gitbook.io/ras/webhooks/coin-webhook-events.md).

# 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**](/ras/webhooks/decrypt-webhook-body.md).

Payment link events are documented separately under [**Payment Link Webhook Events**](/ras/webhooks/payment-link-webhook-events.md).

#### 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 <a href="#buy--sell--swap" id="buy--sell--swap"></a>

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 <a href="#webhook-payload-structure" id="webhook-payload-structure"></a>

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) <a href="#token_received-coin-deposit" id="token_received-coin-deposit"></a>

**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**

```
{
  "event_id": "48291037465829103746",
  "event_type": "token_received",
  "meta_data": {
    "address": "0xfa624f26737cdd712572b45bd5d5ebc9f9f124c3",
    "extra": null,
    "network": "erc20",
    "token": "usdt",
    "value": 2,
    "hash": "0xdeccb101ea58b71a57ca4dc4a2dbf0887de775409a8096b05a277518e96010ce",
    "status": "confirmed",
    "customer": {
      "email": "jean@email.com",
      "first_name": "Jean",
      "last_name": "Billy"
    },
    "address_total_received": 0,
    "genesis": 0
  },
  "datetime": "2025-12-20T20:42:28.000Z"
}
```

***

#### token\_sent (coin send) <a href="#token_sent-coin-send" id="token_sent-coin-send"></a>

**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**

```
{
  "event_id": "91827364501928374650",
  "event_type": "token_sent",
  "meta_data": {
    "destination": "TUyR2sEjzDZNmbnac2ZkJ54h64m6TmVN71",
    "extra": null,
    "network": "trc20",
    "token": "usdt",
    "value": 2,
    "hash": "52CjcHgQHWC1wvGFRSeJVJ18T2hV7DwPimLR13nktLMKK8PgWM99UyAazTTaDD2fkqiAqGNXA3jes7JzRNoe8buB",
    "reference": "10704380386654367514",
    "status": "processed"
  },
  "datetime": "2023-08-10T08:22:17.000Z"
}
```

***

#### token\_refunded (send refund) <a href="#token_refunded-send-refund" id="token_refunded-send-refund"></a>

**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**

```
{
  "event_id": "56473829105647382910",
  "event_type": "token_refunded",
  "meta_data": {
    "network": "trc20",
    "token": "usdt",
    "value": 2,
    "hash": "admin_refund",
    "status": "confirmed",
    "refid": "10704380386654367514"
  },
  "datetime": "2023-08-10T08:22:17.000Z"
}
```

#### Important Notes <a href="#important-notes" id="important-notes"></a>

* 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**](/ras/webhooks/payment-link-webhook-events.md) instead of `token_received`