# Доставка колбэков

Доставка входящих колбэков вебхуков — структура тела HTTP POST, поля статуса рейса и семантика сбоев доставки.



Когда срабатывает событие, на которое оформлена подписка, SkyLink отправляет HTTP-запрос <HttpMethod>POST</HttpMethod> на зарегистрированный вами `url` с `Content-Type: application/json`.

**Важно:*&#x2A; ваш эндпоинт должен ответить **`2xx` в течение \~30 секунд** — медленные обработчики учитываются в пределе автоматического отключения после **10 сбоев подряд**, описанном в [обзоре вебхуков](/docs/v31/webhooks).

## Тело запроса [#request-body]

Полезная нагрузка объединяет метаданные доставки с текущими полями [статуса рейса](/docs/v31/flight-status) (та же структура `departure` / `arrival`):

```json
{
  "event_type": "gate_changed",
  "timestamp": "2026-06-16T14:25:00Z",
  "webhook_id": "00000000-0000-0000-0000-000000000001",
  "flight_number": "BA 123",
  "airline": "British Airways",
  "status": "En Route",
  "departure": {
    "airport": "EGLL",
    "airport_full": "London Heathrow Airport",
    "scheduled_time": "10:30",
    "scheduled_date": "11 Feb",
    "actual_time": "10:35",
    "actual_date": "11 Feb",
    "terminal": "5",
    "gate": "A12",
    "checkin": ""
  },
  "arrival": {
    "airport": "KJFK",
    "airport_full": "John F Kennedy International Airport",
    "scheduled_time": "14:45",
    "scheduled_date": "11 Feb",
    "estimated_time": "14:50",
    "estimated_date": "11 Feb",
    "terminal": "7",
    "gate": "B15",
    "baggage": ""
  }
}
```

| Поле            | Тип               | Обязательный | Описание                                                                                                            |
| --------------- | ----------------- | ------------ | ------------------------------------------------------------------------------------------------------------------- |
| `event_type`    | string            | **Да**       | Какое из событий подписки сработало — см. [Типы событий](/docs/v31/webhooks-subscriptions#event-types)              |
| `timestamp`     | string (ISO 8601) | **Да**       | Момент, когда SkyLink обнаружил изменение и поставил доставку в очередь, — используйте для идемпотентности          |
| `webhook_id`    | string            | **Да**       | UUID подписки из ответов create/list                                                                                |
| `flight_number` | string            | **Да**       | Текущий номер рейса (формат для отображения, может содержать пробел)                                                |
| `airline`       | string            | **Да**       | Отображаемое название авиакомпании                                                                                  |
| `status`        | string            | **Да**       | Текущая метка статуса — та же семантика, что и в эндпоинте [Статус рейса](/docs/v31/flight-status#top-level-fields) |
| `departure`     | object            | **Да**       | Блок вылета — поля полностью совпадают со статусом рейса                                                            |
| `arrival`       | object            | **Да**       | Блок прилёта — поля полностью совпадают со статусом рейса                                                           |

Поля выхода на посадку, терминала и багажа могут быть пустыми строками, если данные не опубликованы, — обрабатывайте их так же, как описано в [примечаниях по интеграции статуса рейса](/docs/v31/flight-status#implementation-notes).

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

Включает `WebhookDelivery` и структуры подписок — тот же набор, что и в разделе [Подписки](/docs/v31/webhooks-subscriptions#client-types):

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

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

Обработчик вебхуков получает запросы `POST` от SkyLink, проверяет полезную нагрузку, сохраняет состояние для идемпотентности и быстро возвращает `2xx`. Пример ниже реализует минимальный обработчик на Python (FastAPI) и TypeScript (Express), демонстрирует дедупликацию и повторно включает подписку через `PATCH` после восстановления из автоматического отключения.

<DocExample id="v31/webhooks/callback-handler" />

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

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

**Восстановление после автоматического отключения.** Исправьте свой эндпоинт, затем отправьте `PATCH` для подписки с `{ "active": true }` — см. [Включение / отключение вебхука](/docs/v31/webhooks-subscriptions#enable-disable-webhook). SkyLink не отправляет пропущенные события повторно.

**Только HTTPS.** URL колбэка должен быть публично доступен по TLS.

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

Сбои доставки (ответ не `2xx` или тайм-аут) увеличивают счётчик сбоев подряд для подписки. После **10** сбоев SkyLink автоматически отключает подписку — ошибка `403` из-за ограничений тарифа при создании: [обзор вебхуков](/docs/v31/webhooks#error-responses).