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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.apollopayment.io/english-2/webhooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.