# Webhook-Abonnements

SkyLink-Webhook-Abonnements erstellen, auflisten, aktivieren, deaktivieren und löschen — eine Flugnummer mit HTTPS-Callbacks überwachen.



Erstellen, listen, aktivieren, deaktivieren und löschen Sie Webhook-Abonnements für Ihren API-Schlüssel. Jedes Abonnement überwacht eine `flight_number` und stellt passende Ereignisse an Ihre HTTPS-Callback-URL zu — den Body des eingehenden POST finden Sie unter [Callback-Zustellung](/docs/v31/webhooks-callback). Tariflimits und Abfrageintervall: [Webhooks-Übersicht](/docs/v31/webhooks).

<DocJumpNav>
  <DocJumpLink href="#create-webhook" icon="solar:add-circle-bold-duotone">
    Erstellen
  </DocJumpLink>

  <DocJumpLink href="#list-webhooks" icon="solar:list-bold-duotone">
    Auflisten
  </DocJumpLink>

  <DocJumpLink href="#enable-disable-webhook" icon="solar:pause-bold-duotone">
    Aktivieren / deaktivieren
  </DocJumpLink>

  <DocJumpLink href="#delete-webhook" icon="solar:trash-bin-trash-bold-duotone">
    Löschen
  </DocJumpLink>
</DocJumpNav>

<DocRequirements>
  <DocRequirementAuth />
</DocRequirements>

<a id="create-webhook" />

## Webhook erstellen [#create-webhook]

Registrieren Sie eine HTTPS-URL, die `POST`-Anfragen empfängt, wenn abonnierte Ereignisse für einen gefilterten Flug eintreten.

<DocRequirements>
  <DocRequirement label="Tarif" href="/docs/rate-limits#plans">
    Pro, Ultra oder Mega — mit BASIC können keine Webhooks erstellt werden
  </DocRequirement>
</DocRequirements>

Senden Sie <HttpMethod>POST</HttpMethod> mit einem JSON-Body.

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

| Feld          | Typ       | Erforderlich | Beschreibung                                                                        |
| ------------- | --------- | ------------ | ----------------------------------------------------------------------------------- |
| `url`         | string    | Ja           | HTTPS-Callback-URL, an die SkyLink per `POST` sendet                                |
| `event_types` | string\[] | Ja           | Ein oder mehrere Ereignistyp-Strings (siehe [Ereignistypen](#event-types))          |
| `filters`     | object    | Ja           | Muss `flight_number` enthalten — die zu überwachende IATA-Flugnummer, z. B. `BA123` |

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

`201 Created` — liefert das erstellte Abonnementobjekt:

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

| Feld          | Typ       | Erforderlich | Beschreibung                                                                     |
| ------------- | --------- | ------------ | -------------------------------------------------------------------------------- |
| `id`          | string    | **Ja**       | UUID des Abonnements — als `webhook_id` in den Pfaden für Patch/Delete verwenden |
| `url`         | string    | **Ja**       | Registrierte Callback-URL                                                        |
| `event_types` | string\[] | **Ja**       | Abonnierte Ereignisse                                                            |
| `filters`     | object    | **Ja**       | Filterobjekt (enthält `flight_number`)                                           |
| `active`      | boolean   | **Ja**       | Ob Zustellungen aktiviert sind                                                   |

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

## Webhooks auflisten [#list-webhooks]

Liefert alle Webhook-Abonnements, die Ihrem API-Schlüssel zugeordnet sind.

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

| Feld       | Typ     | Erforderlich | Beschreibung                                                       |
| ---------- | ------- | ------------ | ------------------------------------------------------------------ |
| `count`    | integer | **Ja**       | Anzahl der zurückgegebenen Abonnements                             |
| `webhooks` | array   | **Ja**       | Abonnementobjekte (gleicher Aufbau wie die Antwort beim Erstellen) |

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

## Webhook aktivieren / deaktivieren [#enable--disable-webhook]

Schalten Sie ein Abonnement ein oder aus, ohne es zu löschen. Verwenden Sie dies, um Zustellungen fortzusetzen, nachdem Sie einen fehlerhaften Endpoint behoben haben — siehe [Callback-Zustellung](/docs/v31/webhooks-callback#implementation-notes).

Senden Sie <HttpMethod>PATCH</HttpMethod> mit der ID des Abonnements im Pfad.

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

| Parameter    | Typ           | Erforderlich | Beschreibung                                 |
| ------------ | ------------- | ------------ | -------------------------------------------- |
| `webhook_id` | string (path) | Ja           | UUID des Abonnements aus Erstellen/Auflisten |

| Body-Feld | Typ     | Erforderlich | Beschreibung                                                       |
| --------- | ------- | ------------ | ------------------------------------------------------------------ |
| `active`  | boolean | Ja           | `true`, um Zustellungen fortzusetzen, `false`, um sie zu pausieren |

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

`200 OK` — liefert das aktualisierte Abonnementobjekt (gleiche Felder wie die Antwort beim Erstellen).

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

## Webhook löschen [#delete-webhook]

Entfernt ein Abonnement dauerhaft. Sie können nur Webhooks löschen, die mit Ihrem API-Schlüssel erstellt wurden.

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

| Parameter    | Typ           | Erforderlich | Beschreibung         |
| ------------ | ------------- | ------------ | -------------------- |
| `webhook_id` | string (path) | Ja           | UUID des Abonnements |

`204 No Content` — leerer Body bei Erfolg.

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

## Ereignistypen [#event-types]

Liefert die unterstützten Strings für Webhook-Ereignistypen für das Array `event_types` beim [Erstellen eines Abonnements](#create-webhook).

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

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

| Ereignis           | Auslöser                                                                       |
| ------------------ | ------------------------------------------------------------------------------ |
| `status_changed`   | Sammelereignis — ein beliebiges überwachtes Feld hat sich geändert             |
| `flight_delayed`   | Der Status weist auf eine Verspätung hin oder die Abflugzeit hat sich geändert |
| `flight_cancelled` | Flug annulliert                                                                |
| `flight_boarding`  | Boarding läuft                                                                 |
| `flight_landed`    | Flug gelandet / angekommen                                                     |
| `gate_changed`     | Abflug- oder Ankunftsgate hat sich geändert                                    |

Rufen Sie die unterstützten Ereignistyp-Strings einmal beim Start ab und hinterlegen Sie sie im Dropdown Ihres Abonnementformulars.

<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-Typen [#client-types]

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

## Integration [#integration]

Webhook-Integrationen im Produktivbetrieb registrieren ein Abonnement pro überwachtem Flug (oder verwenden eine einzige URL mit serverseitigem Routing), prüfen eingehende Zustellungen und pausieren Abonnements, wenn Reisen abgeschlossen sind. Das folgende Beispiel listet Ereignistypen und bestehende Abonnements auf und zeigt Hilfsfunktionen für Erstellen/Patch/Delete mit Timeouts.

Ihr Callback-Endpoint sollte schnell mit `2xx` antworten. Den Body des eingehenden POST und Beispiele für Handler finden Sie unter [Callback-Zustellung](/docs/v31/webhooks-callback).

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

### Hinweise zur Implementierung [#implementation-notes]

**Wichtig:** Verwenden Sie einen öffentlich erreichbaren HTTPS-Endpoint. Für die lokale Entwicklung ist in der Regel ein Tunnel erforderlich (ngrok, Cloudflare Tunnel).

**Wichtig:** Dasselbe Gate oder derselbe Status kann über mehrere Abfragen hinweg mehrere Ereignisse auslösen — deduplizieren Sie in Ihrem Handler anhand von `flight_number` + `event_type` + `timestamp`.

**Wiederherstellung nach automatischer Deaktivierung.** Beheben Sie das Problem an Ihrem Endpoint und senden Sie dann einen `PATCH` an das Abonnement mit `{ "active": true }`, um die Zustellungen fortzusetzen. SkyLink stellt verpasste Ereignisse nicht erneut zu.

## Fehlerantworten [#error-responses]

Tarifbedingtes `403`: [Webhooks-Übersicht](/docs/v31/webhooks#error-responses). Endpointspezifisch:

### 404 — nicht gefunden oder nicht Ihr Eigentum [#404--not-found-or-not-owned]

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

Wird von Patch und Delete zurückgegeben, wenn die `webhook_id` unbekannt ist oder zu einem anderen API-Schlüssel gehört.