# Вебхуки

Вебхуки предоставляют возможность получать обновления по интересующим [темам][topics], как только они произошли в
системе ATI.SU.

## Требования к вебхукам

Для того чтобы обеспечить безопасность и стабильную работу, есть несколько требований, которым должен удовлетворять
вебхук:

- не является открытым и угадываемым, то есть третьи лица не должны иметь возможности узнать о его существовании;
- если используется DNS-имя, оно должно разрешаться в публичный[^1] IPv4 адрес;
- если используется IP-адрес, он должен быть публичным[^1] IPv4 адресом;
- доступен по протоколу HTTP**S**;
- уникален на каждую подписку;
- реализует механизм [аутентификации][authentication].

## Рекомендации по реализации

### 1. Время ответа

На ответ вебхуку дается 20 секунд, поэтому
рекомендуется реализовывать его таким образом, чтобы ответ означал факт получения сообщения, а не его обработки.

### 2. Уникальность

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

### 3. TLS

Сообщения могут содержать закрытую информацию, поэтому отправка их в незашифрованном виде недопустима. Если у вас нет
возможности использовать доверенный сертификат, напишите на почту [api@ati.su](mailto:api@ati.su).

## Использование API

Для существования вебхука необходимы два метода по одному URL. Первый (GET) отвечает за управление состоянием, а
второй (POST) — за передачу сообщений.

### Создание вебхука

Создание вебхука происходит в два этапа: отправка запроса на создание и верификация.

#### Отправка запроса на создание

Чтобы подписаться на события через вебхуки, необходимо [выбрать тему](https://ati.su/developers/raw/api/webhooks/topics/index.md) и указать её в параметре `topic`. Для
тем подписки, которые позволяют подписаться на [события по чужим сущностям][topics-with-filter], необходимо
задать тип подписки `complex` в параметре `subscription_type`, а также заполнить параметры фильтра в соответствии с темой и
указать их в параметре `subscription` [запроса на создание вебхука](#post-webhooks-v1-create).

Параметр `subscription`

**Пример**

```json
{
  "channel": "cargoes.on_boards",
  "boards": [
    "string"
  ]
}
```

**Описание полей модели**
- `channel` — Каналы подписки - `cargoes.on_boards` — [Грузы на площадках](/api/webhooks/topics-with-filter/cargoes-on-boards/) - `auctions.on_boards` — [Торги на площадках](/api/webhooks/topics-with-filter/auctions-on-boards/)
- `boards` — Идентификаторы [площадок](https://ati.su/developers/raw/api/boards.md#get-v2-boards-public-boards-canView) для подписки


Параметр `callback` должен содержать URL вебхука. В URL допустимы параметры запроса, которые будут переданы при вызове
вебхука. Параметры запроса можно использовать, например, для привязки вебхука к пользователю:

```http
https://example.org/webhook?userId=00000000
```

<a id="post-webhooks-v1-create"></a>

**Версия: OAuth2.0 v1**

Создать вебхук

**Пример запроса (curl):**

```bash
curl 'https://api.ati.su/webhooks/v1/create' \
  -X 'POST' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "topic": "cargoes.on_boards",
  "callback": "https://example.com/webhook?userId=000000",
  "subscription_type": "complex",
  "subscription": {
    "channel": "cargoes.on_boards",
    "boards": [
      "644bdc87dbd6fc3747887c7b"
    ]
  }
}'
```

**OpenAPI схема:** [JSON](https://ati.su/developers/raw/api/webhooks/index.openapi.json)

**Описание полей запроса**
- `topic` — Тема
- `callback` — URL
- `subscription_type` — Тип подписки вебхука - `normal` — Обычная - `complex` — С возможностью настройки фильтров
- `subscription` — Параметры подписки с возможностью настройки фильтров

**Пример ответа (4XX)**

```json
{
  "error_code": "string",
  "reason": "string",
  "details": "?",
  "error_list": [
    {}
  ]
}
```

**Описание полей ответа**
- `error_code` — Код ошибки
- `reason` — Причина ошибки
- `details` — Дополнительные параметры
- `error_list` — Вложенные ошибки

<a id="post-webhooks-v1-create"></a>

**Версия: OAuth2.0 v2**

Создать вебхук

**Пример запроса (curl):**

```bash
curl 'https://api.ati.su/gw/oauth2/webhooks/v1/create' \
  -X 'POST' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "topic": "cargoes.on_boards",
  "callback": "https://example.com/webhook?userId=000000",
  "subscription_type": "complex",
  "subscription": {
    "channel": "cargoes.on_boards",
    "boards": [
      "644bdc87dbd6fc3747887c7b"
    ]
  }
}'
```

**OpenAPI схема:** [JSON](https://ati.su/developers/raw/api/webhooks/index.openapi.json)

**Описание полей запроса**
- `topic` — Тема
- `callback` — URL
- `subscription_type` — Тип подписки вебхука - `normal` — Обычная - `complex` — С возможностью настройки фильтров
- `subscription` — Параметры подписки с возможностью настройки фильтров

**Пример ответа (4XX)**

```json
{
  "error_code": "string",
  "reason": "string",
  "details": "?",
  "error_list": [
    {}
  ]
}
```

**Описание полей ответа**
- `error_code` — Код ошибки
- `reason` — Причина ошибки
- `details` — Дополнительные параметры
- `error_list` — Вложенные ошибки


В ответе содержится заголовок `Location` с URL [GET-метода проверки состояния][get-status] созданного вебхука.

#### Верификация

После отправки запроса на создание, вебхук проходит верификацию. Вызывается GET метод по URL вебхука с параметрами
`challenge` и `topic`, а также параметрами указанными при создании.

**Пример верификационного запроса**

```http
GET /webhook?status=verification&verification_status=progress&topic=orders&challenge=608b672ed0a5aaecc2d42488 HTTP/1.1
Host: example.org:443
Date: Thu, 01 Jan 1970 00:00:00 GMT
Digest: 47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=
Accept: application/json
Authorization: HMAC-SHA-256 Credential=6447f577905114d5b9b2c618&SignedHeaders=Date;Digest;Host&Signature=IFfS27QZuXLTNV9idpwnUNDSiayHYAJO0IcoJy2pHy8=
```


Вебхук должен ответить в течение 20 секунд на верификационный запрос JSON-строкой с содержимым параметра `challenge`.

Верификационный запрос, так же как и все остальные, имеет заголовок `Authorization`, поэтому возможна его
[аутентификация][authentication]. При его поступлении следует получить сгенерированный ключ с помощью [метода проверки
состояния вебхука][get-status] (поле `hook.key`).

**Пример ответа на верификационный запрос**

```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 26

"608b672ed0a5aaecc2d42488"
```


Как только ответ будет получен, отправится [оповещение о смене состояния](#оповещения-о-смене-состояния-вебхука). После
успешной верификации, отключите логику обработки параметра `challenge` для данного вебхука, чтобы избежать ошибок.

Если верификация провалилась, узнать причину можно с помощью [метода проверки состояния вебхука][get-status]. Вебхук
будет находиться в состоянии `verification`.

### Проверка состояния вебхука

#### Проверка состояния одного вебхука

<a id="get-webhooks-v1-status-{id}"></a>

**Версия: OAuth2.0 v1**

Получить состояние вебхука

**Пример запроса (curl):**

```bash
curl 'https://api.ati.su/webhooks/v1/status/string' \
  -X 'GET' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: application/json'
```

**OpenAPI схема:** [JSON](https://ati.su/developers/raw/api/webhooks/index.openapi.json)

**Пример ответа (200)**

```json
{
  "status": "deactivated",
  "hook": {
    "id": "string",
    "callback": "string",
    "topic": "string",
    "application_id": "string",
    "contact_id": 0,
    "key": "string",
    "first_failure_date": "1970-01-01T00:00:00.000Z"
  }
}
```

**Описание полей ответа**
- `status` — Идентификатор состояния вебхука - `created` — Создан - `verification` — Проверяется - `active` — Активен - `removed` — Удален - `deactivated` — Деактивирован > Хук деактивируется, если на протяжении нескольких дней ни одна отправка в него не удалась
- `hook` — Проверяемый вебхук
- `hook.id` — Идентификатор
- `hook.callback` — URL
- `hook.topic` — Тема
- `hook.application_id` — Идентификатор приложения
- `hook.contact_id` — Идентификатор контакта
- `hook.key` — Ключ, используемый для подписывания запросов

**Пример ответа (4XX)**

```json
{
  "error_code": "string",
  "reason": "string",
  "details": "?",
  "error_list": [
    {}
  ]
}
```

**Описание полей ответа**
- `error_code` — Код ошибки
- `reason` — Причина ошибки
- `details` — Дополнительные параметры
- `error_list` — Вложенные ошибки

<a id="get-webhooks-v1-status-{id}"></a>

**Версия: OAuth2.0 v2**

Получить состояние вебхука

**Пример запроса (curl):**

```bash
curl 'https://api.ati.su/gw/oauth2/webhooks/v1/status/string' \
  -X 'GET' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: application/json'
```

**OpenAPI схема:** [JSON](https://ati.su/developers/raw/api/webhooks/index.openapi.json)

**Пример ответа (200)**

```json
{
  "status": "deactivated",
  "hook": {
    "id": "string",
    "callback": "string",
    "topic": "string",
    "application_id": "string",
    "contact_id": 0,
    "key": "string",
    "first_failure_date": "1970-01-01T00:00:00.000Z"
  }
}
```

**Описание полей ответа**
- `status` — Идентификатор состояния вебхука - `created` — Создан - `verification` — Проверяется - `active` — Активен - `removed` — Удален - `deactivated` — Деактивирован > Хук деактивируется, если на протяжении нескольких дней ни одна отправка в него не удалась
- `hook` — Проверяемый вебхук
- `hook.id` — Идентификатор
- `hook.callback` — URL
- `hook.topic` — Тема
- `hook.application_id` — Идентификатор приложения
- `hook.contact_id` — Идентификатор контакта
- `hook.key` — Ключ, используемый для подписывания запросов

**Пример ответа (4XX)**

```json
{
  "error_code": "string",
  "reason": "string",
  "details": "?",
  "error_list": [
    {}
  ]
}
```

**Описание полей ответа**
- `error_code` — Код ошибки
- `reason` — Причина ошибки
- `details` — Дополнительные параметры
- `error_list` — Вложенные ошибки


Для [тем подписки с фильтром][topics-with-filter] также доступно получение параметров фильтра.

<a id="get-webhooks-v1-subscriptions-{id}"></a>

**Версия: OAuth2.0 v1**

Получить параметры фильтра

**Пример запроса (curl):**

```bash
curl 'https://api.ati.su/webhooks/v1/subscriptions/string' \
  -X 'GET' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: application/json'
```

**OpenAPI схема:** [JSON](https://ati.su/developers/raw/api/webhooks/index.openapi.json)

**Пример ответа (200)**

```json
{
  "channel": "cargoes.on_boards",
  "boards": [
    "string"
  ]
}
```

**Описание полей ответа**
- `channel` — Каналы подписки - `cargoes.on_boards` — [Грузы на площадках](/api/webhooks/topics-with-filter/cargoes-on-boards/) - `auctions.on_boards` — [Торги на площадках](/api/webhooks/topics-with-filter/auctions-on-boards/)
- `boards` — Идентификаторы [площадок](https://ati.su/developers/raw/api/boards.md#get-v2-boards-public-boards-canView) для подписки

<a id="get-webhooks-v1-subscriptions-{id}"></a>

**Версия: OAuth2.0 v2**

Получить параметры фильтра

**Пример запроса (curl):**

```bash
curl 'https://api.ati.su/gw/oauth2/webhooks/v1/subscriptions/string' \
  -X 'GET' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: application/json'
```

**OpenAPI схема:** [JSON](https://ati.su/developers/raw/api/webhooks/index.openapi.json)

**Пример ответа (200)**

```json
{
  "channel": "cargoes.on_boards",
  "boards": [
    "string"
  ]
}
```

**Описание полей ответа**
- `channel` — Каналы подписки - `cargoes.on_boards` — [Грузы на площадках](/api/webhooks/topics-with-filter/cargoes-on-boards/) - `auctions.on_boards` — [Торги на площадках](/api/webhooks/topics-with-filter/auctions-on-boards/)
- `boards` — Идентификаторы [площадок](https://ati.su/developers/raw/api/boards.md#get-v2-boards-public-boards-canView) для подписки


#### Проверка состояния нескольких вебхуков

<a id="get-webhooks-v1-status"></a>

**Версия: OAuth2.0 v1**

Получить состояние нескольких вебхуков

**Пример запроса (curl):**

```bash
curl 'https://api.ati.su/webhooks/v1/status?statuses=created' \
  -X 'GET' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: application/json'
```

**OpenAPI схема:** [JSON](https://ati.su/developers/raw/api/webhooks/index.openapi.json)

**Пример ответа (200)**

```json
[
  {
    "status": "deactivated",
    "hook": {
      "id": "string",
      "callback": "string",
      "topic": "string",
      "application_id": "string",
      "contact_id": 0,
      "key": "string",
      "first_failure_date": "1970-01-01T00:00:00.000Z"
    }
  }
]
```

**Описание полей ответа**
- `[].status` — Идентификатор состояния вебхука - `created` — Создан - `verification` — Проверяется - `active` — Активен - `removed` — Удален - `deactivated` — Деактивирован > Хук деактивируется, если на протяжении нескольких дней ни одна отправка в него не удалась
- `[].hook` — Проверяемый вебхук
- `[].hook.id` — Идентификатор
- `[].hook.callback` — URL
- `[].hook.topic` — Тема
- `[].hook.application_id` — Идентификатор приложения
- `[].hook.contact_id` — Идентификатор контакта
- `[].hook.key` — Ключ, используемый для подписывания запросов

<a id="get-webhooks-v1-status"></a>

**Версия: OAuth2.0 v2**

Получить состояние нескольких вебхуков

**Пример запроса (curl):**

```bash
curl 'https://api.ati.su/gw/oauth2/webhooks/v1/status?statuses=created' \
  -X 'GET' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: application/json'
```

**OpenAPI схема:** [JSON](https://ati.su/developers/raw/api/webhooks/index.openapi.json)

**Пример ответа (200)**

```json
[
  {
    "status": "deactivated",
    "hook": {
      "id": "string",
      "callback": "string",
      "topic": "string",
      "application_id": "string",
      "contact_id": 0,
      "key": "string",
      "first_failure_date": "1970-01-01T00:00:00.000Z"
    }
  }
]
```

**Описание полей ответа**
- `[].status` — Идентификатор состояния вебхука - `created` — Создан - `verification` — Проверяется - `active` — Активен - `removed` — Удален - `deactivated` — Деактивирован > Хук деактивируется, если на протяжении нескольких дней ни одна отправка в него не удалась
- `[].hook` — Проверяемый вебхук
- `[].hook.id` — Идентификатор
- `[].hook.callback` — URL
- `[].hook.topic` — Тема
- `[].hook.application_id` — Идентификатор приложения
- `[].hook.contact_id` — Идентификатор контакта
- `[].hook.key` — Ключ, используемый для подписывания запросов


### Оповещения о смене состояния вебхука

GET-метод по URL вебхука используется также для оповещений о смене его (вебхука) состояния. Во все вызовы передается
параметр `topic`, обозначающий тему подписки.

| Событие                                           | Параметры                                                                                                              | Описание                                                                                                                 |
| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Провал верификации                                | <span class="nowrap">status: `verification`</span><br/><span class="nowrap">verification_status: `failed`</span>       | Проблемы с верификацией.                                                                                                 |
| <span id="провал-отправки">Провал отправки</span> | <span class="nowrap">distribution_status: `failed`</span><br/><span class="nowrap">since: `YYYY-MM-DDThh:mm:ss`</span> | Проблемы с отправкой сообщения. В параметре `since` указана дата первой проваленной отправки.                            |
| Провал повторной отправки                         | <span class="nowrap">distribution_status: `failed_retry`</span><br/><span class="nowrap">failed_count: число</span>    | Проблемы с повторной отправкой сообщений. В параметре `failed_count` указано количество повторно отправляемых сообщений. |
| Остальные изменения состояния вебхука             | <span class="nowrap">status: одно из значений поля [status][get-status]</span>                                         |

Оповещение о смене статуса не ожидает ответа.

### Получение сообщений

При возникновении события, вызывается POST метод вебхука с параметром `topic`. В теле запроса передается одна или
несколько [обновленных сущностей][topics] (параметр `entities[].entity`) и другие параметры события.

Соответствие порядка возникновения событий и отправки сообщений не гарантируется. Поэтому, при получении сообщения,
необходимо сравнивать параметр `action_date` текущего и предыдущего сообщений.

Тело запроса

**Пример**

```json
{
  "topic": "orders",
  "entities": [
    {
      "entity_id": "4ea8c372-9510-4880-a80d-fb9ac19129cf",
      "action_date": "2021-04-30T05:12:41.687Z",
      "entity": {
        "id": "4ea8c372-9510-4880-a80d-fb9ac19129cf"
      }
    }
  ],
  "is_retry": false
}
```

**Описание полей модели**
- `topic` — Тема
- `entities` — Сообщения
- `entities[].entity_id` — Идентификатор отправляемой сущности
- `entities[].action_date` — Дата события
- `entities[].entity` — Отправляемая сущность
- `is_retry` — Является ли отправка повторной


**Пример отправки сообщения**

```http
POST /webhook?topic=orders HTTP/1.1
Host: example.org:443
Date: Thu, 01 Jan 1970 00:00:00 GMT
Digest: SypZnuCTiysyLuUz9DOYckaU/vf0zrzdxKL1j/sHemg=
Content-Type: application/json
Content-Length: 208
Authorization: HMAC-SHA-256 Credential=6447f577905114d5b9b2c618&SignedHeaders=Date;Digest;Host&Signature=V8CpKji2ysF5h5VVerhcq/GMQGxoHwf0EcGiDIL41e0=

{"topic": "orders", "entities": [{"entity_id": "4ea8c372-9510-4880-a80d-fb9ac19129cf", "action_date": "2021-04-30T05:12:41.687Z", "entity": {"id": "4ea8c372-9510-4880-a80d-fb9ac19129cf"}}], "is_retry": false}
```


Ожидается ответ с кодом 2xx (Successful)[^2] на протяжении 20 секунд. В ином случае отправка помечается проваленной, и
отправляется [оповещение об изменении состояния вебхука](#провал-отправки).

Для временной приостановки получения сообщений, можно использовать ответ 429 (Too Many Requests)[^4] с заголовком
Retry-After[^5]. Приостановка возможна не более чем на 1 день.

Если был получен ответ 410 (Gone)[^3], вебхук удаляется без возможности восстановления.

#### Повторные отправки

Как только вебхук успешно примет сообщение, будет предпринята попытка повторно отправить сообщения, отправка которых
провалилась ранее. Отличить повторную отправку от первоначальной можно по значению `true` в заголовке `ATI-Is-Retry`
запроса. В случае провала повторной отправки, она будет отложена до успешного получения вебхуком нового сообщения.

Если отправки проваливаются на протяжении 4 дня, вебхук
деактивируется. Возобновление его работы возможно только через повторное создание.

До тех пор, пока вебхук не удален, можно получить его проваленные отправки.

<a id="get-webhooks-v1-distributions-failed-{id}"></a>

**Версия: OAuth2.0 v1**

Получить проваленные отправки

**Пример запроса (curl):**

```bash
curl 'https://api.ati.su/webhooks/v1/distributions/failed/string?since=1970-01-01T00%3A00%3A00.000Z' \
  -X 'GET' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: application/json'
```

**OpenAPI схема:** [JSON](https://ati.su/developers/raw/api/webhooks/index.openapi.json)

**Пример ответа (200)**

```json
[
  {
    "entity_id": "string",
    "action_date": "1970-01-01T00:00:00.000Z",
    "status": "failed",
    "entity": null
  }
]
```

**Описание полей ответа**
- `[].entity_id` — Идентификатор отправляемой сущности
- `[].action_date` — Дата события
- `[].status` — Идентификатор состояния отправки - `failed` — Провалена
- `[].entity` — Отправляемая сущность

**Пример ответа (4XX)**

```json
{
  "error_code": "string",
  "reason": "string",
  "details": "?",
  "error_list": [
    {}
  ]
}
```

**Описание полей ответа**
- `error_code` — Код ошибки
- `reason` — Причина ошибки
- `details` — Дополнительные параметры
- `error_list` — Вложенные ошибки

<a id="get-webhooks-v1-distributions-failed-{id}"></a>

**Версия: OAuth2.0 v2**

Получить проваленные отправки

**Пример запроса (curl):**

```bash
curl 'https://api.ati.su/gw/oauth2/webhooks/v1/distributions/failed/string?since=1970-01-01T00%3A00%3A00.000Z' \
  -X 'GET' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: application/json'
```

**OpenAPI схема:** [JSON](https://ati.su/developers/raw/api/webhooks/index.openapi.json)

**Пример ответа (200)**

```json
[
  {
    "entity_id": "string",
    "action_date": "1970-01-01T00:00:00.000Z",
    "status": "failed",
    "entity": null
  }
]
```

**Описание полей ответа**
- `[].entity_id` — Идентификатор отправляемой сущности
- `[].action_date` — Дата события
- `[].status` — Идентификатор состояния отправки - `failed` — Провалена
- `[].entity` — Отправляемая сущность

**Пример ответа (4XX)**

```json
{
  "error_code": "string",
  "reason": "string",
  "details": "?",
  "error_list": [
    {}
  ]
}
```

**Описание полей ответа**
- `error_code` — Код ошибки
- `reason` — Причина ошибки
- `details` — Дополнительные параметры
- `error_list` — Вложенные ошибки


### Редактирование вебхука

Изменение параметров вебхука не предусмотрено, но для [тем подписки с фильтром][topics-with-filter] возможно
редактирование фильтра с помощью соответствующего метода. Изменение канала подписки невозможно.

<a id="put-webhooks-v1-subscriptions-{id}"></a>

**Версия: OAuth2.0 v1**

Отредактировать параметры фильтра

**Пример запроса (curl):**

```bash
curl 'https://api.ati.su/webhooks/v1/subscriptions/string' \
  -X 'PUT' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "channel": "cargoes.on_boards",
  "boards": [
    "string"
  ]
}'
```

**OpenAPI схема:** [JSON](https://ati.su/developers/raw/api/webhooks/index.openapi.json)

**Описание полей запроса**
- `channel` — Каналы подписки - `cargoes.on_boards` — [Грузы на площадках](/api/webhooks/topics-with-filter/cargoes-on-boards/) - `auctions.on_boards` — [Торги на площадках](/api/webhooks/topics-with-filter/auctions-on-boards/)
- `boards` — Идентификаторы [площадок](https://ati.su/developers/raw/api/boards.md#get-v2-boards-public-boards-canView) для подписки

**Пример ответа (200)**

```json
{
  "channel": "cargoes.on_boards",
  "boards": [
    "string"
  ]
}
```

**Описание полей ответа**
- `channel` — Каналы подписки - `cargoes.on_boards` — [Грузы на площадках](/api/webhooks/topics-with-filter/cargoes-on-boards/) - `auctions.on_boards` — [Торги на площадках](/api/webhooks/topics-with-filter/auctions-on-boards/)
- `boards` — Идентификаторы [площадок](https://ati.su/developers/raw/api/boards.md#get-v2-boards-public-boards-canView) для подписки

<a id="put-webhooks-v1-subscriptions-{id}"></a>

**Версия: OAuth2.0 v2**

Отредактировать параметры фильтра

**Пример запроса (curl):**

```bash
curl 'https://api.ati.su/gw/oauth2/webhooks/v1/subscriptions/string' \
  -X 'PUT' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "channel": "cargoes.on_boards",
  "boards": [
    "string"
  ]
}'
```

**OpenAPI схема:** [JSON](https://ati.su/developers/raw/api/webhooks/index.openapi.json)

**Описание полей запроса**
- `channel` — Каналы подписки - `cargoes.on_boards` — [Грузы на площадках](/api/webhooks/topics-with-filter/cargoes-on-boards/) - `auctions.on_boards` — [Торги на площадках](/api/webhooks/topics-with-filter/auctions-on-boards/)
- `boards` — Идентификаторы [площадок](https://ati.su/developers/raw/api/boards.md#get-v2-boards-public-boards-canView) для подписки

**Пример ответа (200)**

```json
{
  "channel": "cargoes.on_boards",
  "boards": [
    "string"
  ]
}
```

**Описание полей ответа**
- `channel` — Каналы подписки - `cargoes.on_boards` — [Грузы на площадках](/api/webhooks/topics-with-filter/cargoes-on-boards/) - `auctions.on_boards` — [Торги на площадках](/api/webhooks/topics-with-filter/auctions-on-boards/)
- `boards` — Идентификаторы [площадок](https://ati.su/developers/raw/api/boards.md#get-v2-boards-public-boards-canView) для подписки


### Удаление вебхука

При удалении вебхука, прекращается отправка сообщений в него, а также удаляются
его [проваленные отправки][failed-distributions].

<a id="delete-webhooks-v1-delete-{id}"></a>

**Версия: OAuth2.0 v1**

Удалить вебхук

**Пример запроса (curl):**

```bash
curl 'https://api.ati.su/webhooks/v1/delete/string' \
  -X 'DELETE' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: application/json'
```

**OpenAPI схема:** [JSON](https://ati.su/developers/raw/api/webhooks/index.openapi.json)

**Пример ответа (4XX)**

```json
{
  "error_code": "string",
  "reason": "string",
  "details": "?",
  "error_list": [
    {}
  ]
}
```

**Описание полей ответа**
- `error_code` — Код ошибки
- `reason` — Причина ошибки
- `details` — Дополнительные параметры
- `error_list` — Вложенные ошибки

<a id="delete-webhooks-v1-delete-{id}"></a>

**Версия: OAuth2.0 v2**

Удалить вебхук

**Пример запроса (curl):**

```bash
curl 'https://api.ati.su/gw/oauth2/webhooks/v1/delete/string' \
  -X 'DELETE' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: application/json'
```

**OpenAPI схема:** [JSON](https://ati.su/developers/raw/api/webhooks/index.openapi.json)

**Пример ответа (4XX)**

```json
{
  "error_code": "string",
  "reason": "string",
  "details": "?",
  "error_list": [
    {}
  ]
}
```

**Описание полей ответа**
- `error_code` — Код ошибки
- `reason` — Причина ошибки
- `details` — Дополнительные параметры
- `error_list` — Вложенные ошибки


[^1]: [RFC 1918 | Private Address Space](https://datatracker.ietf.org/doc/html/rfc1918#section-3)

[^2]: [RFC 7231 | Successful 2xx](https://datatracker.ietf.org/doc/html/rfc7231#section-6.3)

[^3]: [RFC 7231 | 410 Gone](https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.9)

[^4]: [RFC 6585 | 429 Too Many Requests](https://datatracker.ietf.org/doc/html/rfc6585#section-4)

[^5]: [RFC 7231 | Retry-After](https://datatracker.ietf.org/doc/html/rfc7231#section-7.1.3)

[topics]: topics/
[topics-with-filter]: topics/#темы-подписки-с-фильтром
[authentication]: authentication/
[get-status]: #get-webhooks-v1-status-{id}
[failed-distributions]: #get-webhooks-v1-distributions-failed-%7bid%7d
---

## llms.txt

Индекс ключевых страниц документации для LLM и AI-агентов доступен в [основном llms.txt](https://ati.su/developers/llms.txt).