# Webhook notification

Below are the details of the webhook requests are sent from CoinsDo to webhook URL.

## **Setup**

1. In your merchant account, go to API Access.
2. Toggle on the webhook event you want and insert webhook URL.
3. Click confirm once done. 
4. (Optional) Add this IP into your network whitelisting list if needed, our API webhook notification will be fired from this IP address only.

<figure><img src="https://3529283920-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fbq6zziU9PCtrTYtaegKj%2Fuploads%2FN4BIIPHD8vxbV5bWjsYo%2Fimage.png?alt=media&#x26;token=17a11662-8c27-4748-8253-a0e2d93d56c4" alt=""><figcaption></figcaption></figure>

## Webhook Request

<mark style="color:green;">`POST`</mark> `/{webhookURL}`

#### Header

<table><thead><tr><th width="128.38411458333331">Parameter</th><th width="100.15625">Required</th><th>Value</th></tr></thead><tbody><tr><td>Content-Type</td><td>Yes</td><td>application/json</td></tr></tbody></table>

#### Body

<table><thead><tr><th width="110.1796875">Parameter</th><th width="100.4375">Required</th><th width="79.5390625">Type</th><th>Description</th></tr></thead><tbody><tr><td>sign</td><td>Yes</td><td>string</td><td>Signature</td></tr><tr><td>data</td><td>Yes</td><td>string</td><td>Content (JSON string), refer to Webhook Events section.</td></tr></tbody></table>

#### **Example**

```
{
    "data": "{\"txTime\":\"1661336430\",\"businessId\":\"0x6305fb61_JDXqh_0_2\",\"mainnet\":\"TRX\",\"withdrawStatus\":\"1\",\"txMemo\":\"0\",\"feeSymbol\":\"TRX\",\"blockNumber\":\"29232059\",\"txFee\":\"8.34196\",\"coinName\":\"JST\",\"txHash\":\"b29e917066ed433b5d2753ae07a9b4bd71245509f8f9de51ec5a2e43425f91a8\"}",
    "sign": "1b248bbf33dffb5004f4f179bb4b20e1a455e5c7d3be366c0b07e75ddc229d10"
}
```

## **Webhook Events**

Below shows all the available events and its respective data content.

<table data-full-width="false"><thead><tr><th width="99.99609375">Module</th><th width="233.96875">Event</th><th>Trigger</th></tr></thead><tbody><tr><td>CoinSend</td><td>Dispatch</td><td>Upon approval or rejection of a transfer record.</td></tr><tr><td>CoinGet</td><td>Collection</td><td>When a token sweep event is recorded.</td></tr><tr><td>CoinGet</td><td>Collection receiving</td><td>When a new receiving record is confirmed by 1 block.</td></tr><tr><td>CoinGet</td><td>Confirmation count</td><td>When a receiving record is confirmed by a specific number of blocks defined in <a href="../../coinget/setup/currency-control">Currency Control</a>.</td></tr></tbody></table>

### Transfer record

Trigger upon approval / rejection / failure of a transfer record in CoinSend.

<table data-full-width="false"><thead><tr><th width="143.32421875">Parameter</th><th width="107.3125">Type</th><th>Description</th><th data-hidden>Required</th></tr></thead><tbody><tr><td>businessId</td><td>string</td><td>Custom business identifier</td><td>Yes</td></tr><tr><td>withdrawStatus</td><td>string</td><td>Transfer status<br>1. Success<br>2. Rejected<br>5. Cancelled<br>6. Cancelled due to address restriction (Must enable in CoinSend Client page)<br><img src="https://3529283920-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fbq6zziU9PCtrTYtaegKj%2Fuploads%2F0x04IUn9x1EZ8mtkvs5K%2Fimage.png?alt=media&#x26;token=6db9e835-fc75-4e85-8d96-06c73e907abb" alt=""><br><br>7. Cancelled due to signature expired</td><td>Yes</td></tr><tr><td>txHash</td><td>string</td><td>Transaction hash</td><td>No</td></tr><tr><td>blockNumber</td><td>number</td><td>Block number where the transaction was recorded</td><td>No</td></tr><tr><td>txTime</td><td>timestamp</td><td>Transaction confirmation timestamp(seconds)</td><td>No</td></tr><tr><td>txFee</td><td>decimal</td><td>Gas/network fee</td><td>No</td></tr><tr><td>feeSymbol</td><td>string</td><td>Currency used for txFee</td><td>No</td></tr><tr><td>businessScene</td><td>string</td><td>Business scene string submitted via API request</td><td>No</td></tr><tr><td>txMemo</td><td>string</td><td>Transaction memo</td><td>No</td></tr><tr><td>mainnet</td><td>string</td><td>Network</td><td>Yes</td></tr><tr><td>coinName</td><td>string</td><td>Token symbol</td><td>Yes</td></tr></tbody></table>

```
{
  "businessId": "SOL_SPL2025061315143701",
  "txHash": "3p2iop22eHVfq59iz22rfMkagXyKrmiPurcDPJVtRv3vqgMLXmCUR14oDHJK63NJmyyUHzuHWFh3dmsZdipxBFBi",
  "withdrawStatus": "1",
  "blockNumber": "346485584",
  "txTime": "1749802811",
  "txFee": "0.000155",
  "feeSymbol": "SOL",
  "businessScene": "1",
  "txMemo": "pymongo_withdraw_live",
  "mainnet": "SOL",
  "coinName": "USDT",
  "deviceUuid": "2559DA72-696A-4CA9-ADE0-CFA537C9D09F"
}
```

### Receiving record (confirmed by 1 block)

Triggered upon new incoming transaction recorded and confirmed by 1 block.

<table><thead><tr><th width="174.06640625">Parameter</th><th width="99.64453125">Required</th><th width="110.796875">Type</th><th>Description</th></tr></thead><tbody><tr><td>txHash</td><td>Yes</td><td>string</td><td>Transaction hash</td></tr><tr><td>txIndex</td><td>Yes</td><td>string</td><td>Default 0, could be other than 0 if the transaction has multiple transfer</td></tr><tr><td>fromAddress</td><td>Yes</td><td>string</td><td>Sender's address</td></tr><tr><td>toAddress</td><td>Yes</td><td>string</td><td>Receiving address</td></tr><tr><td>amount</td><td>Yes</td><td>decimal</td><td>Token amount</td></tr><tr><td>txFee</td><td>Yes</td><td>decimal</td><td>Gas/network fee</td></tr><tr><td>txTime</td><td>Yes</td><td>timestamp</td><td>Transaction confirmation timestamp(seconds)</td></tr><tr><td>txMemo</td><td>No</td><td>string</td><td>On-chain memo</td></tr><tr><td>deviceUuid</td><td>Yes</td><td>string</td><td>Wallet ID of the receiving address</td></tr><tr><td>currency</td><td>Yes</td><td>string</td><td>Token protocol (ERC20 / BEP20 / etc) or coin name if native token transfer</td></tr><tr><td>flag</td><td>Yes</td><td>string</td><td>Contract address or coin name if native token transfer</td></tr><tr><td>blockNumber</td><td>Yes</td><td>string</td><td>Block number where the transaction was recorded</td></tr><tr><td>isReachedConfirm</td><td>Yes</td><td>string</td><td>0. Has not been confirmed by the required blocks<br>1. Has been confirmed by the required blocks<br>Default as 1</td></tr><tr><td>blockConfirm</td><td>Yes</td><td>string</td><td>Number of blocks confirmed</td></tr><tr><td>mainnet</td><td>Yes</td><td>string</td><td>Network</td></tr><tr><td>coinName</td><td>Yes</td><td>string</td><td>Currency name</td></tr><tr><td>coinsDoId</td><td>Yes</td><td>string</td><td>CoinsDo ID (refer to currency control)</td></tr><tr><td>protocol</td><td>Yes</td><td>string</td><td>Token's protocol (ERC20, BEP20 and etc)</td></tr><tr><td>tokenAddress</td><td>Yes</td><td>string</td><td>Token address (refer to currency control)</td></tr><tr><td>coinType</td><td>Yes</td><td>string</td><td>0. Coin<br>1. Token</td></tr></tbody></table>

#### **Example**

```
{
  "txHash": "f0b9bc10e203573ac116929235cec213ca855e0c564a5f3ec23bf15752146f97",
  "txIndex": "0",
  "fromAddress": "EQBlee9uqqUqNNWjoS4JdYTMFkveceWQuZYAiR9j54jqOzQk",
  "toAddress": "EQBtY8DtdKvkucg8CieDQgdr58B-X16DWJOVr1z3L8vQZoY0",
  "amount": "77",
  "txFee": "0.026167903",
  "txTime": "1750667516",
  "txMemo": "pymongo_withdraw_live",
  "deviceUuid": "0B08AF6B-151C-4BBE-A152-F6496077CEAA",
  "currency": "JETTON",
  "flag": "EQCFcjD08uBGAKyEUmSc_J7qpCXexQQUsulQVlae8Eaon-Pp",
  "blockNumber": "49131390",
  "isReachedConfirm": "0",
  "blockConfirm": "1",
  "mainnet": "TON",
  "coinName": "j7$",
  "coinsDoId": "823",
  "protocol": "JETTON",
  "tokenAddress": "EQCFcjD08uBGAKyEUmSc_J7qpCXexQQUsulQVlae8Eaon-Pp",
  "coinType": "1"
}
```

### Receiving record (confirmed after required blocks)

Triggered upon new incoming transaction recorded and confirmed by 1 block.

<table><thead><tr><th width="174.06640625">Parameter</th><th width="99.64453125">Required</th><th width="110.796875">Type</th><th>Description</th></tr></thead><tbody><tr><td>txHash</td><td>Yes</td><td>string</td><td>Transaction hash</td></tr><tr><td>txIndex</td><td>Yes</td><td>string</td><td>Default 0, could be other than 0 if the transaction has multiple transfer</td></tr><tr><td>fromAddress</td><td>Yes</td><td>string</td><td>Sender's address</td></tr><tr><td>toAddress</td><td>Yes</td><td>string</td><td>Receiving address</td></tr><tr><td>amount</td><td>Yes</td><td>decimal</td><td>Token amount</td></tr><tr><td>txFee</td><td>Yes</td><td>decimal</td><td>Gas/network fee</td></tr><tr><td>txTime</td><td>Yes</td><td>timestamp</td><td>Transaction confirmation timestamp(seconds)</td></tr><tr><td>txMemo</td><td>No</td><td>string</td><td>On-chain memo</td></tr><tr><td>deviceUuid</td><td>Yes</td><td>string</td><td>Wallet ID of the receiving address</td></tr><tr><td>currency</td><td>Yes</td><td>string</td><td>Token protocol (ERC20 / BEP20 / etc) or coin name if native token transfer</td></tr><tr><td>flag</td><td>Yes</td><td>string</td><td>Contract address or coin name if native token transfer</td></tr><tr><td>feeSymbol</td><td>Yes</td><td>string</td><td>Gas fee unit/symbol</td></tr><tr><td>blockNumber</td><td>Yes</td><td>string</td><td>Block number where the transaction was recorded</td></tr><tr><td>checkSign</td><td>Yes</td><td>string</td><td>Verification signature, refer to checkSign section below</td></tr><tr><td>addressRemark</td><td>No</td><td>string</td><td>Address remark added in receiving address record</td></tr><tr><td>isReachedConfirm</td><td>Yes</td><td>string</td><td>0. Has not been confirmed by the required blocks<br>1. Has been confirmed by the required blocks<br>Default as 1</td></tr><tr><td>blockConfirm</td><td>Yes</td><td>string</td><td>Number of blocks confirmed</td></tr><tr><td>mainnet</td><td>Yes</td><td>string</td><td>Network</td></tr><tr><td>coinName</td><td>Yes</td><td>string</td><td>Currency name</td></tr><tr><td>coinsDoId</td><td>Yes</td><td>string</td><td>CoinsDo ID (refer to currency control)</td></tr><tr><td>protocol</td><td>Yes</td><td>string</td><td>Token's protocol (ERC20, BEP20 and etc)</td></tr><tr><td>tokenAddress</td><td>Yes</td><td>string</td><td>Token address (refer to currency control)</td></tr><tr><td>coinType</td><td>Yes</td><td>string</td><td>0. Coin<br>1. Token</td></tr><tr><td>checkCode</td><td>Yes</td><td>string</td><td>Transaction check result code (refer to Checkcode table below)</td></tr><tr><td>recordId</td><td>Yes</td><td>string</td><td>Unique record ID</td></tr><tr><td>manualCallback</td><td>Yes</td><td>string</td><td>0. Request was triggered automatically<br>1. Request was triggered manually</td></tr></tbody></table>

{% hint style="success" %}

#### Tips

To identify the token received correctly, we strongly recommend to verify using mainnet, coinsDoId, and tokenAddress
{% endhint %}

#### **CheckSign**

* checkSign is a signature generated by the CoinSend client for verification by a third party from the client device.
* The webhook request will only be triggered after the verification is successfully completed.
* If the verification fails, the CoinSend client will retry up to 10 times before sending the request.
* Signed data is a concatenation of checkCode + recordId + txHash.

{% hint style="info" %}

To turn on 3rd-party verification, go to CoinGet > CoinGet client > Transaction check\
\
![](https://3529283920-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fbq6zziU9PCtrTYtaegKj%2Fuploads%2FFrLOJIwDeRW72JQsdJLn%2Fimage.png?alt=media\&token=76b1ecc7-0aaf-49f0-be82-16c12935852f)
{% endhint %}

#### **Checkcode**

<table><thead><tr><th width="101.2109375">checkCode</th><th width="172.60546875">Address checking</th><th width="164.3359375">3rd-part trx checking</th><th>Description</th></tr></thead><tbody><tr><td>-1</td><td>Checking error</td><td>Checking error</td><td>Unknown error</td></tr><tr><td>0</td><td>Checking success</td><td>Checking success</td><td>Checking success</td></tr><tr><td>1</td><td>Checking error</td><td>Check pending</td><td>Address does not exists</td></tr><tr><td>2</td><td>Checking success</td><td>Checking success</td><td>Data not match</td></tr><tr><td>3</td><td>Checking success</td><td>Checking error</td><td>Transaction failed</td></tr><tr><td>4</td><td>Checking success</td><td>Checking error</td><td>Transaction checking failed</td></tr><tr><td>5</td><td>Checking success</td><td>Checking error</td><td>Transaction not found</td></tr><tr><td>6</td><td>Checking success</td><td>Checking disabled</td><td>Checking disabled</td></tr><tr><td>7</td><td>Checking error</td><td>Check pending</td><td>Address not found</td></tr></tbody></table>

#### **Example**

```
{
  "txHash": "a0b2e575f033d460b6b5f8c0c4268d47e6b3c70d127c8ccdbc1bdd3b80a336a2",
  "txIndex": "0",
  "fromAddress": "EQBlee9uqqUqNNWjoS4JdYTMFkveceWQuZYAiR9j54jqOzQk",
  "toAddress": "EQBtY8DtdKvkucg8CieDQgdr58B-X16DWJOVr1z3L8vQZoY0",
  "amount": "0.27",
  "txFee": "0.002859258",
  "txTime": "1748568966",
  "txMemo": "pymongo_withdraw_live",
  "deviceUuid": "0B08AF6B-151C-4BBE-A152-F6496077CEAA",
  "currency": "TON",
  "flag": "TON",
  "feeSymbol": "TON",
  "blockNumber": "48317552",
  "checkSign": "ovk1JUpIAx6yVlICMSm9/RehchWuLnvT+KE6roBn+Ad1YGRVfQPklDkdt1nKmIJkVb+iM7EoCUa4B+kskJyMZpba0lOx9LUT/Y+5UYodagyMQjZ/cDIypTeVNrHe21jNuCheimH+kwsgZ0XnvvLVOxDJqGopcRgYEfgPeMJYB7Q=",
  "addressRemark": "CUST_123456",
  "isReachedConfirm": "1",
  "blockConfirm": "1",
  "mainnet": "TON",
  "coinName": "TON",
  "coinsDoId": "781",
  "protocol": "",
  "tokenAddress": "",
  "coinType": "0",
  "checkCode": "6",
  "recordId": "1928264349282017282",
  "manualCallback": "0"
}
```

### Collection / Token Sweep

<table><thead><tr><th width="174.06640625">Parameter</th><th width="99.64453125">Required</th><th width="110.796875">Type</th><th>Description</th></tr></thead><tbody><tr><td>txHash</td><td>Yes</td><td>string</td><td>Transaction hash</td></tr><tr><td>fromAddress</td><td>Yes</td><td>string</td><td>Sender's address</td></tr><tr><td>toAddress</td><td>Yes</td><td>string</td><td>Receiving address</td></tr><tr><td>amount</td><td>Yes</td><td>decimal</td><td>Token amount</td></tr><tr><td>txFee</td><td>Yes</td><td>decimal</td><td>Gas/network fee</td></tr><tr><td>txTime</td><td>Yes</td><td>timestamp</td><td>Transaction confirmation timestamp(seconds)</td></tr><tr><td>txStatus</td><td>Yes</td><td>string</td><td>Token sweep status, default to 1</td></tr><tr><td>txMemo</td><td>No</td><td>string</td><td>On-chain memo</td></tr><tr><td>deviceUuid</td><td>Yes</td><td>string</td><td>Wallet ID of the receiving address</td></tr><tr><td>currency</td><td>Yes</td><td>string</td><td>Token protocol (ERC20 / BEP20 / etc) or coin name if native token transfer</td></tr><tr><td>flag</td><td>Yes</td><td>string</td><td>Contract address or coin name if native token transfer</td></tr><tr><td>feeSymbol</td><td>Yes</td><td>string</td><td>Gas fee unit/symbol</td></tr><tr><td>blockNumber</td><td>Yes</td><td>string</td><td>Block number where the transaction was recorded</td></tr><tr><td>blockConfirm</td><td>Yes</td><td>string</td><td>Number of blocks confirmed</td></tr><tr><td>mainnet</td><td>Yes</td><td>string</td><td>Network</td></tr><tr><td>coinName</td><td>Yes</td><td>string</td><td>Currency name</td></tr><tr><td>coinsDoId</td><td>Yes</td><td>string</td><td>CoinsDo ID (refer to currency control)</td></tr><tr><td>protocol</td><td>Yes</td><td>string</td><td>Token's protocol (ERC20, BEP20 and etc)</td></tr><tr><td>tokenAddress</td><td>Yes</td><td>string</td><td>Token address (refer to currency control)</td></tr><tr><td>recordId</td><td>Yes</td><td>string</td><td>Unique record ID</td></tr></tbody></table>

#### **Example**

```
{
  "txHash": "605bf33c0dddcebb7125663796f012ce164797fb977e986bdba953cd0d3ca774",
  "fromAddress": "EQBtY8DtdKvkucg8CieDQgdr58B-X16DWJOVr1z3L8vQZoY0",
  "toAddress": "EQBlee9uqqUqNNWjoS4JdYTMFkveceWQuZYAiR9j54jqOzQk",
  "amount": "77",
  "txFee": "0.103249624",
  "txTime": "1750667717",
  "txStatus": "1",
  "deviceUuid": "0B08AF6B-151C-4BBE-A152-F6496077CEAA",
  "currency": "JETTON",
  "flag": "EQCFcjD08uBGAKyEUmSc_J7qpCXexQQUsulQVlae8Eaon-Pp",
  "feeSymbol": "TON",
  "blockNumber": "49131472",
  "mainnet": "TON",
  "coinName": "j7$",
  "coinsDoId": "823",
  "protocol": "JETTON",
  "tokenAddress": "EQCFcjD08uBGAKyEUmSc_J7qpCXexQQUsulQVlae8Eaon-Pp",
  "coinType": "1",
  "recordId": "1937066913330962433"
}
```

## **Handling Webhook**

Make sure to respond with a "code": 200 as below, otherwise the system will retry request every 5 seconds up to 5 times, and can be triggered manually after that.

```
{
  "code": 200, // Status code
  "msg": "Success", // Remarks
  "data": null // Response
}
```

{% hint style="info" %}

To view webhook request log, you can add callback notification column in receiving / dispatch record table by clicking into the gear icon > customize form as shown below.\
\
![](https://3529283920-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fbq6zziU9PCtrTYtaegKj%2Fuploads%2F2BBsRNkJy9ORnrpHgJTW%2Fimage.png?alt=media\&token=04186dfa-4bfe-4d1b-b1b0-7fabf916c4b8)\
\
and click into the callback status\
\
![](https://3529283920-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fbq6zziU9PCtrTYtaegKj%2Fuploads%2FlkxnXlmSwDgAwghqIGLF%2Fimage.png?alt=media\&token=e58bf540-e6eb-424d-80bd-eae648933f53)
{% endhint %}