# Подписки на вебхуки

Создание, просмотр, включение, отключение и удаление подписок на вебхуки SkyLink — отслеживание номера рейса с HTTPS-колбэками.



Создавайте, просматривайте, включайте, отключайте и удаляйте подписки на вебхуки, привязанные к вашему API-ключу. Каждая подписка отслеживает один `flight_number` и доставляет соответствующие события на ваш HTTPS-URL колбэка — структуру тела входящего POST-запроса см. в разделе [Доставка колбэков](/docs/v31/webhooks-callback). Лимиты тарифов и интервал опроса: [обзор вебхуков](/docs/v31/webhooks).

<DocJumpNav>
  <DocJumpLink href="#create-webhook" icon="solar:add-circle-bold-duotone">
    Создание
  </DocJumpLink>

  <DocJumpLink href="#list-webhooks" icon="solar:list-bold-duotone">
    Список
  </DocJumpLink>

  <DocJumpLink href="#enable-disable-webhook" icon="solar:pause-bold-duotone">
    Включение / отключение
  </DocJumpLink>

  <DocJumpLink href="#delete-webhook" icon="solar:trash-bin-trash-bold-duotone">
    Удаление
  </DocJumpLink>
</DocJumpNav>

<DocRequirements>
  <DocRequirementAuth />
</DocRequirements>

<a id="create-webhook" />

## Создание вебхука [#create-webhook]

Зарегистрируйте HTTPS-URL, чтобы получать запросы `POST`, когда для отфильтрованного рейса срабатывают события из подписки.

<DocRequirements>
  <DocRequirement label="Тариф" href="/docs/rate-limits#plans">
    Pro, Ultra или Mega — на тарифе BASIC создавать вебхуки нельзя
  </DocRequirement>
</DocRequirements>

Отправьте <HttpMethod>POST</HttpMethod> с телом в формате JSON.

<DocApiPath method="POST" path="/webhooks" />

| Поле          | Тип       | Обязательный | Описание                                                                               |
| ------------- | --------- | ------------ | -------------------------------------------------------------------------------------- |
| `url`         | string    | Да           | HTTPS-URL колбэка, на который SkyLink будет отправлять `POST`                          |
| `event_types` | string\[] | Да           | Одна или несколько строк типов событий (см. [Типы событий](#event-types))              |
| `filters`     | object    | Да           | Должен содержать `flight_number` — номер рейса IATA для отслеживания, например `BA123` |

```json
{
  "url": "https://your-server.example.com/webhook",
  "event_types": ["flight_delayed", "flight_landed", "gate_changed"],
  "filters": {
    "flight_number": "BA123"
  }
}
```

`201 Created` — возвращает созданный объект подписки:

```json
{
  "id": "00000000-0000-0000-0000-000000000001",
  "url": "https://your-server.example.com/webhook",
  "event_types": ["flight_delayed", "flight_landed", "gate_changed"],
  "filters": { "flight_number": "BA123" },
  "active": true
}
```

| Поле          | Тип       | Обязательный | Описание                                                          |
| ------------- | --------- | ------------ | ----------------------------------------------------------------- |
| `id`          | string    | **Да**       | UUID подписки — используйте как `webhook_id` в путях patch/delete |
| `url`         | string    | **Да**       | Зарегистрированный URL колбэка                                    |
| `event_types` | string\[] | **Да**       | События, на которые оформлена подписка                            |
| `filters`     | object    | **Да**       | Объект фильтра (содержит `flight_number`)                         |
| `active`      | boolean   | **Да**       | Включена ли доставка                                              |

<APIPage document="&#x22;https://api.skylinkapi.com/v3.1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/webhooks&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />

<a id="list-webhooks" />

## Список вебхуков [#list-webhooks]

Возвращает все подписки на вебхуки, связанные с вашим API-ключом.

<DocApiPath method="GET" path="/webhooks" />

```json
{
  "count": 1,
  "webhooks": [
    {
      "id": "00000000-0000-0000-0000-000000000001",
      "url": "https://your-server.example.com/webhook",
      "event_types": ["status_changed"],
      "filters": { "flight_number": "BA123" },
      "active": true
    }
  ]
}
```

| Поле       | Тип     | Обязательный | Описание                                                       |
| ---------- | ------- | ------------ | -------------------------------------------------------------- |
| `count`    | integer | **Да**       | Число возвращённых подписок                                    |
| `webhooks` | array   | **Да**       | Объекты подписок (та же структура, что и в ответе на создание) |

<APIPage document="&#x22;https://api.skylinkapi.com/v3.1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/webhooks&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />

<a id="enable-disable-webhook" />

## Включение / отключение вебхука [#enable--disable-webhook]

Включайте или отключайте подписку, не удаляя её. Используйте это, чтобы возобновить доставку после исправления неработающего эндпоинта, — см. [Доставка колбэков](/docs/v31/webhooks-callback#implementation-notes).

Отправьте <HttpMethod>PATCH</HttpMethod> с идентификатором подписки в пути.

<DocApiPath method="PATCH" path="/webhooks/{webhook_id}" />

| Параметр     | Тип           | Обязательный | Описание                             |
| ------------ | ------------- | ------------ | ------------------------------------ |
| `webhook_id` | string (path) | Да           | UUID подписки из ответов create/list |

| Поле тела | Тип     | Обязательный | Описание                                               |
| --------- | ------- | ------------ | ------------------------------------------------------ |
| `active`  | boolean | Да           | `true` — возобновить доставку, `false` — приостановить |

```json
{ "active": false }
```

`200 OK` — возвращает обновлённый объект подписки (те же поля, что и в ответе на создание).

<APIPage document="&#x22;https://api.skylinkapi.com/v3.1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/webhooks/{webhook_id}&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;}]" />

<a id="delete-webhook" />

## Удаление вебхука [#delete-webhook]

Безвозвратно удаляет подписку. Удалять можно только вебхуки, созданные с вашим API-ключом.

<DocApiPath method="DELETE" path="/webhooks/{webhook_id}" />

| Параметр     | Тип           | Обязательный | Описание      |
| ------------ | ------------- | ------------ | ------------- |
| `webhook_id` | string (path) | Да           | UUID подписки |

`204 No Content` — при успехе тело пустое.

<APIPage document="&#x22;https://api.skylinkapi.com/v3.1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/webhooks/{webhook_id}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;}]" />

<a id="event-types" />

## Типы событий [#event-types]

Возвращает поддерживаемые строки типов событий вебхуков для массива `event_types` при [создании подписки](#create-webhook).

<DocApiPath method="GET" path="/webhooks/events" />

```json
{
  "event_types": [
    "flight_boarding",
    "flight_cancelled",
    "flight_delayed",
    "flight_landed",
    "gate_changed",
    "status_changed"
  ]
}
```

| Событие            | Условие срабатывания                                        |
| ------------------ | ----------------------------------------------------------- |
| `status_changed`   | Общее событие — изменилось любое отслеживаемое поле         |
| `flight_delayed`   | Статус указывает на задержку или изменилось время вылета    |
| `flight_cancelled` | Рейс отменён                                                |
| `flight_boarding`  | Идёт посадка                                                |
| `flight_landed`    | Рейс приземлился / прибыл                                   |
| `gate_changed`     | Изменился выход на посадку при вылете или выход при прилёте |

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

<DocExample id="v31/webhooks/events-fetch" />

<APIPage document="&#x22;https://api.skylinkapi.com/v3.1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/webhooks/events&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />

## Клиентские типы [#client-types]

<DocClientTypes id="v31/webhooks/subscription-types" />

## Интеграция [#integration]

В продакшн-интеграциях вебхуков подписка регистрируется для каждого отслеживаемого рейса (или один URL используется повторно с маршрутизацией на стороне сервера), входящие доставки проверяются, а подписки приостанавливаются по завершении поездок. Пример ниже получает список типов событий, список существующих подписок и демонстрирует вспомогательные функции create/patch/delete с тайм-аутами.

Ваш эндпоинт колбэка должен быстро отвечать `2xx`. Структуру тела входящего POST-запроса и примеры обработчиков см. в разделе [Доставка колбэков](/docs/v31/webhooks-callback).

<DocExample id="v31/webhooks/manage-fetch" />

### Примечания по реализации [#implementation-notes]

**Важно:** используйте публично доступный HTTPS-эндпоинт. Для локальной разработки обычно нужен туннель (ngrok, Cloudflare Tunnel).

**Важно:** один и тот же выход на посадку или статус может вызвать несколько событий в разных циклах опроса — выполняйте дедупликацию в обработчике по `flight_number` + `event_type` + `timestamp`.

**Восстановление после автоматического отключения.** Исправьте свой эндпоинт, затем отправьте `PATCH` для подписки с `{ "active": true }`, чтобы возобновить доставку. SkyLink не отправляет пропущенные события повторно.

## Ответы с ошибками [#error-responses]

Ошибка `403` из-за ограничений тарифа: [обзор вебхуков](/docs/v31/webhooks#error-responses). Ошибки, специфичные для эндпоинта:

### 404 — не найден или не принадлежит вам [#404--not-found-or-not-owned]

```json
{
  "detail": "Webhook not found or not owned by you"
}
```

Возвращается при patch и delete, если `webhook_id` неизвестен или принадлежит другому API-ключу.