# Webhooks

### Description

You can configure notifications to be sent to any system that accepts incoming webhooks over the HTTP/HTTPS protocol. To do this, you must specify the Webhook URL when **creating an order**, to which notifications about the order will be sent.

If you do not respond with the status 200, then we will send 6 request: with 10 seconds interval, then 5 with 30 minutes interval, then 4 with 2 hour interval, then 3 with 12 hour interval.

If Webhook URL was provided within API method, it will have following additional headers:

* `x-api-public-key` - public key, which was used in origin request with provided Webhook URL
* `x-api-signature` - signature that was made with same algorithm from "Creating request signature" section

**Server IP addresses:** 92.62.137.125

## Order status webhook

#### Webhook URL example

"successWebhook": "[https://example.com/success-webhook-url"](https://example.com/success-webhook-url)

"errorWebhook": "[https://example.com/error-webhook-url"](https://example.com/error-webhook-url)

> #### Attention
>
> Please note that the statuses `processed`, `expired`, `partial`, `overpaid` \*\* are not final\*\*
>
> When processing a webhook, you should separately process the array of received transactions to correctly process the payment amount

#### Server response example

```javascript
{
  id: 'a020272e-b97a-4ed8-ab74-696426913627',
  advancedBalanceId: '316a59ea-be39-4eaa-9392-6fda708f24d8',
  currency: 'USDT',
  network: 'tron',
  status: 'processed',
  order: '#1234567',
  description: null,
  address: 'TCpyHjEF7weWw2284sy7yYX5KUo9GTs6R6',
  tag: null,
  amount: '0.2',
  received: '0.20000000',
  transactions: [
    {
      id: '9812eb5f-b8b7-4e33-90e7-c8139d7cf46d',
      status: 'processed',
      currency: 'USDT',
      network: 'tron',
      amount: '0.1',
      tx: '86464a34fbecb77d67bda0604a883a796ddc3ccd54854637cd6fa0b95ccf1f3f',
      confirmations: '10',
      sender: 'TUdtD3oXvX37NM5mH5W561p6GSeDHeUDTD',
      priceUSD: '1',
      amountUSD: '0.1'
    },
    {
      id: '87fa47d7-9d83-42d0-9dc9-aba52b9869a3',
      status: 'processed',
      currency: 'USDT',
      network: 'tron',
      amount: '0.1',
      tx: 'fbc94452bc9f2a097a73ade40eada72125224f3a4c39965941a431d641493399',
      confirmations: '10',
      sender: 'TUdtD3oXvX37NM5mH5W561p6GSeDHeUDTD',
      priceUSD: '1',
      amountUSD: '0.1'
    }
  ],
  link: 'https://payment.domain/a020272e-b97a-4ed8-ab74-696426913627',
  successWebhook: 'https://merchant.domain/success',
  errorWebhook: 'https://merchant.domain/error',
  returnUrl: null,
  expiresAt: '2022-07-05T15:40:29.837Z',
  createdAt: '2022-07-05T13:39:26.006Z',
  updatedAt: '2022-07-05T13:42:00.588Z',
  webhookId: "b614475d-aa39-49be-b3bf-1622e357a267"
}

```

## Invoice status webhook

#### Server response example

```json
{
  "id": "fd1dbab8-06c2-4e0e-88fb-32f5e97cc0e2",
  "advancedBalanceId": "316a59ea-be39-4eaa-9392-6fda708f24d8",
  "externalId": "external-merchant-id-1234",
  "orderId": "87fa47d7-9d83-42d0-9dc9-aba52b9869a3",
  "orderLink": "https://payment.domain/87fa47d7-9d83-42d0-9dc9-aba52b9869a3",
  "invoiceLink": "https://invoices.domain/fd1dbab8-06c2-4e0e-88fb-32f5e97cc0e2",
  "status": "PROCESSED",
  "order": "Payment #1234",
  "description": "Payment for ...",
  "currency": "USD",
  "amount": "100",
  "receivedNetwork": "ethereum",
  "receivedCurrency": "USDT",
  "receivedAmount": "101.12",
  "receivedAmountInInvoiceCurrency": "100.92",
  "rate": "0.998",
  "includeFee": true,
  "additionalFees": ["SEPA_WITHDRAWAL"],
  "insurancePercent": "1",
  "slippagePercent": "2.5",
  "transactions": [
    {
      "id": "9812eb5f-b8b7-4e33-90e7-c8139d7cf46d",
      "status": "processed",
      "currency": "USDT",
      "network": "tron",
      "amount": "101.12",
      "tx": "86464a34fbecb77d67bda0604a883a796ddc3ccd54854637cd6fa0b95ccf1f3f",
      "confirmations": "10",
      "sender": "TUdtD3oXvX37NM5mH5W561p6GSeDHeUDTD",
      "priceUSD": "1",
      "amountUSD": "100"
    }
  ],
  "webhookUrl": "https://merchant.domain/webhooks/invoice",
  "returnUrl": "https://merchant.domain/",
  "expiresAt": "2023-09-04T09:00:00.960Z",
  "createdAt": "2023-09-04T06:39:01.960Z",
  "webhookId": "b614475d-aa39-49be-b3bf-1622e357a267"
}
```

Possible values for `status`:

* `CREATED` - created
* `INIT` - the user proceeded to payment
* `PENDING` - waiting for the full amount or waiting for transaction confirmations in the blockchain
* `PROCESSED` - completed
* `PARTIAL` - partial payment
* `REJECTED` - the invoice was rejected, contact support for clarification
* `ERROR` - error during creation or processing
* `EXPIRED` - the invoice has expired

## Withdrawal status webhook

When the withdrawal is completed, a webhook with the status of this payment is sent to the `webhookUrl` specified when creating the withdrawal.

* `addressId` - personal address to which the deposit came
* `userId` - the ID (internal) of the user who owns the personal address
* `clientId` - the ID (external, in your service) of the user who owns the personal address

```json
{
  "id": "fd1dbab8-06c2-4e0e-88fb-32f5e97cc0e2",
  "addressId": "a3018d42-aa59-42f3-a0f9-6d47e461d344",
  "amount": "0.32",
  "currency": "USDT",
  "network": "tron",
  "status": "processed",
  "tx": "46f4c1bafd9925de3d61d8a86d83851e73e",
  "createdAt": "2023-03-21T13:50:48.603Z",
  "updatedAt": "2023-03-21T13:51:14.018Z",
  "webhookId": "b614475d-aa39-49be-b3bf-1622e357a267"
}

```

Possible values for `status`:

* `error` - error occured during withdrawal processing
* `processed` - successful withdrawal

## Billing link status webhook

When the status of a billing link changes, a webhook is sent to the address specified when the link was created.

```json
{
  "id": "9085a4bd-0099-4f8a-9dc5-9a717ab1d93b",
  "merchantId": "dcb1a9fe-4b8d-40f6-baf6-241dc88436d9",
  "clientId": "qw12",
  "clientName": null,
  "clientEmail": "site@domain.com",
  "webhookUrl": "https://site.com/webhook",
  "returnUrl": null,
  "address": "0xf038f6b",
  "currency": "USDC",
  "network": "ethereum",
  "status": "SUCCESS",
  "createdAt": "2023-03-02T10:10:21.064Z",
  "updatedAt": "2023-03-02T10:13:25.509Z",
  "webhookId": "b614475d-aa39-49be-b3bf-1622e357a267"
}

```

## Subscription status webhook

When the subscription status changes or when a payment is made, a webhook is sent to the address specified when the subscription was created.

```json
{
  "id": "d5743dea-5a78-4096-ae07-95b1f10bc5dd",
  "merchantId": "dcb1a9fe-4b8d-40f6-baf6-241dc88436d9",
  "billingLinkId": "e7e7a111-2d24-4aa3-afae-540f313c738b",
  "title": "Flixnet/monthly",
  "description": "Flixnet monthly subscription / HD quality",
  "currency": "USDT",
  "amount": "2.0000000",
  "spendInterval": 120,
  "message": null,
  "webhookUrl": "https://site.com/webhook",
  "status": "ACTIVE",
  "createdAt": "2023-02-27T11:50:53.710Z",
  "updatedAt": "2023-03-01T19:29:04.090Z",
  "paymentEvent": {
    "id": "9c06e989-9d19-461b-bd94-e94032012407",
    "merchantId": "dcb1a9fe-4b8d-40f6-baf6-241dc88436d9",
    "billingLinkId": "e7e7a111-2d24-4aa3-afae-540f313c738b",
    "amount": "2",
    "status": "PROCESSED",
    "tx": "0xdabd91e979122bb78d0a5cf1e5174dff3e10b906a31adbfd625ff80cca14e8c2",
    "createdAt": "2023-03-01T13:11:57.662Z",
    "updatedAt": "2023-03-01T13:14:32.868Z"
  },
  "webhookId": "b614475d-aa39-49be-b3bf-1622e357a267"
}

```

When the subscription status changes, a webhook with the subscription object is sent. In this case, `paymentEvent` is filled only if the webhook event is related to making a payment.

Possible values for `status`:

* `ACTIVE` - subscription active/renewed
* `ERROR` - subscription payment failed
* `DECLINE` - unable to complete the payment (e.g. lack of money)
* `CANCEL` - subscription canceled

The status comment can be contained in the `message` field

After the payment is made, a webhook is sent with the object of this payment in the `paymentEvent` field. Possible values of the `paymentEvent.status` field:

* `PROCESSED` - successful payment
* `ERROR` - unsuccessful payment

## Payment status webhook with free amount

When a payment is completed, a webhook with the status of this payment (the same object as in the `paymentEvent` field of the webhook with the subscription status) is sent to the address specified during the payment request.

```json
{
  "id": "2fa68ddf-2479-47cb-9e66-ae91139c3063",
  "merchantId": "dcb1a9fe-4b8d-40f6-baf6-241dc88436d9",
  "billingLinkId": "6196a1f2-b6b5-40a5-a672-f1ffd70fdd7d",
  "amount": "0.005",
  "status": "PROCESSED",
  "tx": "0x5b9b3b55b366266025e",
  "createdAt": "2023-03-02T06:58:00.365Z",
  "updatedAt": "2023-03-02T07:01:50.693Z",
  "webhookId": "b614475d-aa39-49be-b3bf-1622e357a267"
}

```

Possible values for `status`:

* `PROCESSED` - successful payment
* `ERROR` - unsuccessful payment

## Crosschain bridge operation status webhook

When the operation status changes, a webhook is sent to the address specified when the operation was created

```json
{
  "id": "816a19eb-be39-4eaa-9392-6fda708f24d8",
  "clientId": "...",
  "advancedBalanceId": "316a59ea-be39-4eaa-9392-6fda708f24d8",
  "currency": "USDT",
  "networkFrom": "bsc",
  "networkTo": "tron",
  "status": "PENDING",
  "rejectMessage": null,
  "addressFromId": "fa475cfa-15e8-c31d-7469-5f1168052cd6",
  "addressToId": "607976c9-0270-59a3-a528-0d92489c3fc8",
  "amount": "10000",
  "amountUSD": "10000",
  "blockchainFee": "1.80",
  "blockchainFeeUSD": "1.80",
  "serviceFeeUSD": "1.50",
  "webhookUrl": "https://my-show.com/...",
  "createdAt": "2022-02-02T06:07:34.067Z",
  "webhookId": "b614475d-aa39-49be-b3bf-1622e357a267"
}

```

Available statuses

| **Status** | **Description**        |
| ---------- | ---------------------- |
| CREATED    | Request registered     |
| PENDING    | Being processed        |
| ERROR      | Error during execution |
| REJECTED   | Request denied         |
| PROCESSED  | Success                |

## Crosschain swap status webhook

When the swap status changes, a webhook is sent to the address specified when the swap was created

```json
{
        "id": "816a19eb-be39-4eaa-9392-6fda708f24d8",
        "clientId": "...",
        "advancedBalanceId": "316a59ea-be39-4eaa-9392-6fda708f24d8",
        "currencyFrom": "TRX",
        "currencyTo": "USDT",
        "networkFrom": "tron",
        "networkTo": "bsc",
        "status": "PENDING",
        "rejectMessage": null,
        "addressFromId": "fa475cfa-15e8-c31d-7469-5f1168052cd6",
        "addressToId": "607976c9-0270-59a3-a528-0d92489c3fc8",
        "amountFrom": "100000",
        "amountTo": "10000",
        "price": "0.1",
        "serviceBlockchainFeeSource": "ADDRESS",
        "serviceBlockchainFee": "1.80",
        "serviceBlockchainFeeUSD": "1.80",
        "providerBlockchainFeeSource": "AMOUNT",
        "providerBlockchainFee": "1.80",
        "providerBlockchainFeeUSD": "1.80",
        "serviceFeeSource": "ADVANCE",
        "serviceFee": "1.80",
        "serviceFeeUSD": "1.80",
        "webhookUrl": "https://my-show.com/...",
        "createdAt": "2022-02-02T06:07:34.067Z",
        "webhookId": "b614475d-aa39-49be-b3bf-1622e357a267"
}

```

Available statuses

| **Status** | **Description**        |
| ---------- | ---------------------- |
| CREATED    | Request registered     |
| PENDING    | Being processed        |
| ERROR      | Error during execution |
| REJECTED   | Request denied         |
| PROCESSED  | Success                |

## Webhook for deposit on personal address

When the payment is completed, a webhook with the status of this payment is sent to the URL `depositWebhookUrl` specified when creating the user.

* `addressId` - personal address to which the deposit came
* `userId` - ID of the user who owns the personal address

#### Example

```json
{
  "id": "2fa68ddf-2479-47cb-9e66-ae91139c3063",
  "addressId": "dcb1a9fe-4b8d-40f6-baf6-241dc88436d9",
  "userId": "6196a1f2-b6b5-40a5-a672-f1ffd70fdd7d",
  "amount": "0.005",
  "currency": "USDT",
  "network": "bsc",
  "addressFrom": ["0x....", "0x...."],
  "addressTo": "0x....",
  "status": "PROCESSED",
  "confirmations": 10,
  "tx": "0x5b9b3b55b366266025e",
  "risks": {"level": "yellow", "categories": [{ "level": "yellow", "usdAmount": 41159.8, "category": "stolen funds", "service": "Reported as stolen funds bc1qlf4vel", "exposure": "DIRECT" }],
  "createdAt": "2023-03-02T06:58:00.365Z",
  "updatedAt": "2023-03-02T07:01:50.693Z",
  "webhookId": "b614475d-aa39-49be-b3bf-1622e357a267"
}

```

Possible values of `status`:

* `PENDING` - deposit is in processing
* `PROCESSED` - successful deposit

## Webhook статуса авто-обмена

#### Пример

```json
{
    "id":"25e2d6ab-44a2-4a7f-9898-a1fc8b27ee19",
    "organizationId":"1f07eb01-5fd8-4e05-89b5-bebcd1d1fc39",
    "userId":null,
    "status":"PROCESSED",
    "currencyFrom":"USDT",
    "currencyTo":"BTC",
    "networkFrom":"tron",
    "networkTo":"bitcoin",
    "addressFromId":"5cb5fefa-7e08-453c-8910-3dc268b16e52",
    "addressFrom":"TF4pfwhPsKzHB1bEV6kGt5T3jejLANW2T3",
    "addressTo":"bc1q9zqj930c0ehss7rsg9sg3nhcccys068c5s3max",
    "amountFrom":"31.56426000",
    "amountFromUSD":"31.56",
    "amountTo":"0.00044955",
    "amountToUSD":"31.59",
    "amountToReceive":"0.00020955",
    "rate":"70213.01301301",
    "blockchainFeeFrom":"2.64000000",
    "blockchainFeeFromUSD":"2.64",
    "blockchainFeeTo":"0.00024000",
    "blockchainFeeToUSD":"16.87",
    "serviceFee":"1.5",
    "webhookUrl":"https://...",
    "createdAt":"2024-03-27T12:12:31.688Z",
    "updatedAt":"2024-03-27T12:19:33.768Z",
    "webhookId":"2636d60c-a3f5-4938-bbd6-ca15d365279a"
}

```

Возможные значения `status`:

| Status        | Description                                   |
| ------------- | --------------------------------------------- |
| `PENDING`     | In processing                                 |
| `WITHDRAWING` | Waiting to be sent to the destination address |
| `PROCESSED`   | Successfully                                  |
| `REJECTED`    | Rejected                                      |
| `ERROR`       | Processing error                              |