Подписки на вебхуки
Создавайте, просматривайте, включайте, отключайте и удаляйте подписки на вебхуки, привязанные к вашему API-ключу. Каждая подписка отслеживает один flight_number и доставляет соответствующие события на ваш HTTPS-URL колбэка — структуру тела входящего POST-запроса см. в разделе Доставка колбэков. Лимиты тарифов и интервал опроса: обзор вебхуков.
Требования
x-api-key в каждом запросе (прямая подписка). Подробнее →Создание вебхука
Зарегистрируйте HTTPS-URL, чтобы получать запросы POST, когда для отфильтрованного рейса срабатывают события из подписки.
Требования
Pro, Ultra или Mega — на тарифе BASIC создавать вебхуки нельзя
Подробнее →Отправьте POST с телом в формате JSON.
https://data.skylinkapi.com/v3.1/webhooks| Поле | Тип | Обязательный | Описание |
|---|---|---|---|
url | string | Да | HTTPS-URL колбэка, на который SkyLink будет отправлять POST |
event_types | string[] | Да | Одна или несколько строк типов событий (см. Типы событий) |
filters | object | Да | Должен содержать flight_number — номер рейса IATA для отслеживания, например BA123 |
{
"url": "https://your-server.example.com/webhook",
"event_types": ["flight_delayed", "flight_landed", "gate_changed"],
"filters": {
"flight_number": "BA123"
}
}201 Created — возвращает созданный объект подписки:
{
"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 | Да | Включена ли доставка |
Your SkyLink licence key, for keys bought direct from skylinkapi.com.
In: header
Header Parameters
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
curl -X POST "https://data.skylinkapi.com/v3.1/webhooks" \ -H "Content-Type: application/json" \ -d '{ "event_types": [ "flight_delayed", "flight_landed", "gate_changed" ], "filters": { "flight_number": "BA123" }, "url": "https://your-server.example.com/webhook" }'null{
"detail": [
{
"loc": [
"string"
],
"msg": "string",
"type": "string",
"input": null,
"ctx": {}
}
]
}Список вебхуков
Возвращает все подписки на вебхуки, связанные с вашим API-ключом.
https://data.skylinkapi.com/v3.1/webhooks{
"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 | Да | Объекты подписок (та же структура, что и в ответе на создание) |
Your SkyLink licence key, for keys bought direct from skylinkapi.com.
In: header
Header Parameters
Response Body
application/json
application/json
curl -X GET "https://data.skylinkapi.com/v3.1/webhooks"null{
"detail": [
{
"loc": [
"string"
],
"msg": "string",
"type": "string",
"input": null,
"ctx": {}
}
]
}Включение / отключение вебхука
Включайте или отключайте подписку, не удаляя её. Используйте это, чтобы возобновить доставку после исправления неработающего эндпоинта, — см. Доставка колбэков.
Отправьте PATCH с идентификатором подписки в пути.
https://data.skylinkapi.com/v3.1/webhooks/{webhook_id}| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
webhook_id | string (path) | Да | UUID подписки из ответов create/list |
| Поле тела | Тип | Обязательный | Описание |
|---|---|---|---|
active | boolean | Да | true — возобновить доставку, false — приостановить |
{ "active": false }200 OK — возвращает обновлённый объект подписки (те же поля, что и в ответе на создание).
Your SkyLink licence key, for keys bought direct from skylinkapi.com.
In: header
Path Parameters
Header Parameters
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
curl -X PATCH "https://data.skylinkapi.com/v3.1/webhooks/00000000-0000-0000-0000-000000000001" \ -H "Content-Type: application/json" \ -d '{ "active": true }'null{
"detail": [
{
"loc": [
"string"
],
"msg": "string",
"type": "string",
"input": null,
"ctx": {}
}
]
}Удаление вебхука
Безвозвратно удаляет подписку. Удалять можно только вебхуки, созданные с вашим API-ключом.
https://data.skylinkapi.com/v3.1/webhooks/{webhook_id}| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
webhook_id | string (path) | Да | UUID подписки |
204 No Content — при успехе тело пустое.
Your SkyLink licence key, for keys bought direct from skylinkapi.com.
In: header
Path Parameters
Header Parameters
Response Body
application/json
curl -X DELETE "https://data.skylinkapi.com/v3.1/webhooks/00000000-0000-0000-0000-000000000001"{
"detail": [
{
"loc": [
"string"
],
"msg": "string",
"type": "string",
"input": null,
"ctx": {}
}
]
}Типы событий
Возвращает поддерживаемые строки типов событий вебхуков для массива event_types при создании подписки.
https://data.skylinkapi.com/v3.1/webhooks/events{
"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 | Изменился выход на посадку при вылете или выход при прилёте |
Получите поддерживаемые строки типов событий один раз при запуске и сохраните их для выпадающего списка в форме подписки.
import osimport requestsBASE = "https://data.skylinkapi.com/v3.1"HEADERS = { "x-api-key": os.getenv("SKYLINK_API_KEY") or os.getenv("SKYLINK_API_KEY", "YOUR_API_KEY")}def list_webhook_event_types() -> list[str]: """Return supported webhook event type strings.""" r = requests.get(f"{BASE}/webhooks/events", headers=HEADERS, timeout=(10, 15)) r.raise_for_status() return r.json()["event_types"]if __name__ == "__main__": import json print(json.dumps(list_webhook_event_types(), indent=2))Your SkyLink licence key, for keys bought direct from skylinkapi.com.
In: header
Response Body
application/json
curl -X GET "https://data.skylinkapi.com/v3.1/webhooks/events"nullКлиентские типы
"""Webhook subscription models."""from __future__ import annotationsfrom dataclasses import dataclass@dataclassclass WebhookCreateRequest: url: str event_types: list[str] filters: dict[str, str]@dataclassclass WebhookSubscription: id: str url: str event_types: list[str] filters: dict[str, str] active: bool@dataclassclass WebhookListResponse: count: int webhooks: list[WebhookSubscription]@dataclassclass WebhookEventTypesResponse: event_types: list[str]@dataclassclass WebhookDelivery: """Inbound POST body SkyLink sends to your callback URL.""" event_type: str timestamp: str webhook_id: str flight_number: str airline: str status: str departure: dict[str, str] arrival: dict[str, str]Интеграция
В продакшн-интеграциях вебхуков подписка регистрируется для каждого отслеживаемого рейса (или один URL используется повторно с маршрутизацией на стороне сервера), входящие доставки проверяются, а подписки приостанавливаются по завершении поездок. Пример ниже получает список типов событий, список существующих подписок и демонстрирует вспомогательные функции create/patch/delete с тайм-аутами.
Ваш эндпоинт колбэка должен быстро отвечать 2xx. Структуру тела входящего POST-запроса и примеры обработчиков см. в разделе Доставка колбэков.
import osimport requestsBASE = "https://data.skylinkapi.com/v3.1"HEADERS = { "x-api-key": os.getenv("SKYLINK_API_KEY", "YOUR_API_KEY")}def list_webhook_event_types() -> list[str]: """Return supported webhook event type strings.""" r = requests.get(f"{BASE}/webhooks/events", headers=HEADERS, timeout=(10, 15)) r.raise_for_status() return r.json()["event_types"]def list_webhooks() -> dict: """List webhook subscriptions for the current API key.""" r = requests.get(f"{BASE}/webhooks", headers=HEADERS, timeout=(10, 15)) r.raise_for_status() return r.json()def create_webhook(*, url: str, event_types: list[str], flight_number: str) -> dict: """Create a webhook subscription for a single flight.""" body = { "url": url, "event_types": event_types, "filters": {"flight_number": flight_number.upper().replace(" ", "")}, } r = requests.post(f"{BASE}/webhooks", headers=HEADERS, json=body, timeout=(10, 20)) r.raise_for_status() return r.json()def set_webhook_active(webhook_id: str, *, active: bool) -> dict: """Enable or disable a webhook without deleting it.""" r = requests.patch( f"{BASE}/webhooks/{webhook_id}", headers=HEADERS, json={"active": active}, timeout=(10, 15), ) r.raise_for_status() return r.json()def delete_webhook(webhook_id: str) -> None: """Permanently delete a webhook subscription.""" r = requests.delete(f"{BASE}/webhooks/{webhook_id}", headers=HEADERS, timeout=(10, 15)) r.raise_for_status()if __name__ == "__main__": import json events = list_webhook_event_types() print(json.dumps(events, indent=2))Примечания по реализации
Важно: используйте публично доступный HTTPS-эндпоинт. Для локальной разработки обычно нужен туннель (ngrok, Cloudflare Tunnel).
Важно: один и тот же выход на посадку или статус может вызвать несколько событий в разных циклах опроса — выполняйте дедупликацию в обработчике по flight_number + event_type + timestamp.
Восстановление после автоматического отключения. Исправьте свой эндпоинт, затем отправьте PATCH для подписки с { "active": true }, чтобы возобновить доставку. SkyLink не отправляет пропущенные события повторно.
Ответы с ошибками
Ошибка 403 из-за ограничений тарифа: обзор вебхуков. Ошибки, специфичные для эндпоинта:
404 — не найден или не принадлежит вам
{
"detail": "Webhook not found or not owned by you"
}Возвращается при patch и delete, если webhook_id неизвестен или принадлежит другому API-ключу.