# Webhooks

## Описание

Вы можете настроить отправку уведомлений в любую систему, которая принимает входящие вебхуки по протоколу HTTP/HTTPS. Для этого необходимо указать Webhook URL **при создании ордера**, на который будут отправляться уведомления об ордере.

Если Вы не ответите статусом 200, то мы продолжим слать запрос: первые 6 с интервалом 10 секунд, следующие 5 с интервалом 30 минут, потом 4 с интервалом 2 часа и последние 3 с интервалом 12 часов.

Если Webhook URL был указан через API, то в запросе будут присланы следующие дополнительные заголовки:

* `x-api-public-key` - публичный ключ, с помощью которого был выполнен запрос с указанием Webhook URL
* `x-api-signature` - подись, созданная по принципу, описанному в п. "Формирование подписи запроса"

**IP-адреса сервера:** 92.62.137.125

## Webhook статуса ордера

#### Webhook URL пример

"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)

> #### Внимание
>
> Обратите внимание, что статусы `processed`, `expired`, `partial`, `overpaid` **не являются конечными**
>
> При обработке вебхука вам стоит отдельно обрабатывать массив полученных транзакций для корректной обработки суммы платежа

#### Пример ответа сервера

```json
{
  id: 'a020272e-b97a-4ed8-ab74-696426913627',
  advancedBalanceId: '316a59ea-be39-4eaa-9392-6fda708f24d8',
  currency: 'USDT',
  network: 'tron',
  status: 'processed',
  order: '#12345',
  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"
}

```

## Webhook статуса счета

#### Пример ответа сервера

```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"
}
```

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

* `CREATED` - создан
* `INIT` - пользователь перешел к оплате
* `PENDING` - ожидаение полной суммы или ожидание подтверждений транзакции в блокчейне
* `PROCESSED` - исполнен
* `PARTIAL` - частичная оплата
* `REJECTED` - инвойс отклонен, свяжитесь с поддержкой для уточнения
* `ERROR` - ошибка в процессе создания или обработки
* `EXPIRED` - скрок действия инвойса истек

## Webhook статуса вывода

При завершения вывода присылается вебхук со статусом этого платежа на URL адрес `webhookUrl`, указанный при создании вывода.

* `addressId` - персональный адрес, на который пришел депозит
* `userId` - идентификатор пользователя, владеющего персональным адресом

#### Пример

```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"
}

```

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

* `ERROR` - во время вывода произошла ошибка
* `PROCESSED` - успешный вывод

## Webhook статуса платежной связки

При изменении статуса платежной связки высылается вебхук на адрес, указанный при создании этой связки.

```json
{
  "id": "e457d90c-2321-4f9c-9f71-7a16fecc9b66",
  "merchantId": "dcb1a9fe-4b8d-40f6-baf6-241dc88436d9",
  "clientId": "199933300",
  "network": "bsc",
  "currency": "USDT",
  "address": "0x1d9e9703",
  "status": "SUCCESS",
  "webhookId": "b614475d-aa39-49be-b3bf-1622e357a267"
}

```

## Webhook статуса подписки

При изменении статуса подписки или при проведения платежа высылается вебхук на адрес, указанный при создании подписки.

#### Пример

```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"
}

```

При изменении статуса подписки высылается вебхук с объектом подписки. При этом `paymentEvent` заполняется только если событие вебхука связано с проведением платежа.

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

* `ACTIVE` - подписка активна/возобновлена
* `ERROR` - неуспешный платеж по подписке
* `DECLINE` - невозможно выполнить платеж (напр. нехватка денег)
* `CANCEL` - подписка отменена

Комментарий к статусу может содержаться в поле `message`

После проведения платежа высылается вебхук с объектом этого платежа в поле `paymentEvent`. Возможные значения поля `paymentEvent.status`:

* `PROCESSED` - успешный платеж
* `ERROR` - неуспешный платеж

## Webhook статуса платежа со свободной суммой

При завершения платежа присылается вебхук со статусом этого платежа (тот же объект, что и в поле `paymentEvent` вебхука со статусом подписки) на адрес, указанный при запросе на платеж.

#### Пример

```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"
}

```

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

* `PROCESSED` - успешный платеж
* `ERROR` - неуспешный платеж

## Webhook статуса операции кроссчейн моста

При изменении статуса операции присылается вебхук на адрес, указанный при создании операции

```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"
}

```

Доступные статусы

| **Статус** | **Описание**                 |
| ---------- | ---------------------------- |
| CREATED    | Запрос зарегистрирован       |
| PENDING    | Обрабатывается               |
| ERROR      | Ошибка в процессе исполнения |
| REJECTED   | Запрос отклонен              |
| PROCESSED  | Успех                        |

## Webhook статуса кроссчейн обмена

При изменении статуса обмена присылается вебхук на адрес, указанный при создании обмена

```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"
}

```

Доступные статусы

| **Статус** | **Описание**                 |
| ---------- | ---------------------------- |
| CREATED    | Запрос зарегистрирован       |
| PENDING    | Обрабатывается               |
| ERROR      | Ошибка в процессе исполнения |
| REJECTED   | Запрос отклонен              |
| PROCESSED  | Успех                        |

## Webhook статуса депозита на персональный адрес

При завершения платежа присылается вебхук со статусом этого платежа на URL адрес `depositWebhookUrl`, указанный при создании пользователя.

* `addressId` - персональный адрес, на который пришел депозит
* `userId` - идентификатор пользователя (внутренний), владеющего персональным адресом
* `clientId` - идентификатор пользователя (внешний, в вашей системе), владеющего персональным адресом

#### Пример

```json
{
  "id": "2fa68ddf-2479-47cb-9e66-ae91139c3063",
  "addressId": "dcb1a9fe-4b8d-40f6-baf6-241dc88436d9",
  "userId": "6196a1f2-b6b5-40a5-a672-f1ffd70fdd7d",
  "clientId": "133357",
  "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"
}

```

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

* `PENDING` - платеж в обработке
* `PROCESSED` - успешный платеж

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

| Статус        | Описание                            |
| ------------- | ----------------------------------- |
| `PENDING`     | В обработке                         |
| `WITHDRAWING` | Ожидание отправки на конечный адрес |
| `PROCESSED`   | Успешно                             |
| `REJECTED`    | Отклонен                            |
| `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/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.