# Webhooks

Manage webhook subscriptions for near real-time event notifications. These endpoints enable partners to create, manage, and monitor webhook subscriptions for receiving flight-related events and updates.

**Business Value**
- Receive near real-time notifications for flight events and updates.
- Automate integration workflows with external systems.
- Monitor flight operations and passenger changes in near real-time.
- Reduce polling overhead by using event-driven architecture.

<br/>

**Use Cases**
- Subscribe to flight updates to sync data with external booking systems.
- Monitor passenger count changes for catering and ground service coordination.
- Track aircraft changes for maintenance and operational planning.
- Receive notifications for flight cancellations and time updates.

<br/>

**Available Event Types:**
- `FLIGHT_CREATE`: New flight creation
- `FLIGHT_CANCEL`: Flight cancellation
- `FLIGHT_TIME_UPDATE`: Flight time changes
- `FLIGHT_AIRCRAFT_UPDATE`: Aircraft assignment changes
- `FLIGHT_AIRPORT_UPDATE`: Airport(s) changes
- `FLIGHT_POST_FLIGHT_STATUS`: Post-flight status updates
- `FLIGHT_MOVEMENT_UPDATE`: Flight movement updates
- `FLIGHT_PAX_COUNT_UPDATE`: Passenger count changes
- `FLIGHT_PAX_LIST_UPDATE`: Passenger list changes (e.g. new passengers, updated list, passenger document changes, etc.)


## Get webhook subscriptions

 - [GET /api/v2/webhooks/subscriptions](https://developer.fl3xx.com/reference/v2/webhooks/getwebhooksubscriptions.md): Retrieve all webhook subscriptions for the authenticated partner and operator.

Features:
- Returns all active and inactive webhook subscriptions
- Filtered by partner and operator context

## Create a new webhook subscription

 - [POST /api/v2/webhooks/subscriptions](https://developer.fl3xx.com/reference/v2/webhooks/createwebhooksubscription.md): Create a new webhook subscription for receiving near real-time event notifications.

Features:
- Validates callback URL format, only https is supported
- Sets automatic expiration date (1 month) for subscriptions

Example Use Case: An operations manager needs to receive near real-time notifications when flight times change. By creating a webhook subscription for FLIGHT_TIME_UPDATE events, they can automatically sync flight data with external systems.

## Get webhook subscription by ID

 - [GET /api/v2/webhooks/subscriptions/{subscriptionId}](https://developer.fl3xx.com/reference/v2/webhooks/getwebhooksubscriptionbyid.md): Retrieve a specific webhook subscription by its unique identifier.

Features:
- Returns detailed subscription information

## Update webhook subscription callback URL or status

 - [PATCH /api/v2/webhooks/subscriptions/{subscriptionId}](https://developer.fl3xx.com/reference/v2/webhooks/updatewebhooksubscription.md): Update the callback URL for an existing webhook subscription.

Features:
- Validates new callback URL format, only https is supported
- Updates subscription status to active or inactive

Example Use Case: An operations manager needs to change the webhook endpoint URL after migrating to a new server. Using this endpoint, they can update the callback URL without recreating the entire subscription.

## Delete a webhook subscription

 - [DELETE /api/v2/webhooks/subscriptions/{subscriptionId}](https://developer.fl3xx.com/reference/v2/webhooks/deletewebhooksubscription.md): Delete a webhook subscription and stop receiving notifications for the associated event type.

Features:
- Immediately stops webhook deliveries

Example Use Case: An operations manager needs to stop receiving flight update notifications after completing a system migration. Using this endpoint, they can cleanly remove the webhook subscription.

## Renew a webhook subscription

 - [POST /api/v2/webhooks/subscriptions/{subscriptionId}/renewals](https://developer.fl3xx.com/reference/v2/webhooks/renewwebhooksubscription.md): Renew an existing webhook subscription to extend its expiration date.

Features:
- Extends subscription expiration by 1 month from current expiration date.
- Subscriptions can only be renewed 5 days before expiration.

Example Use Case: An operations manager wants to continue receiving webhook notifications for an existing subscription. Using this endpoint, they can extend the subscription without recreating it.

## Get webhook deliveries

 - [GET /api/v2/webhooks/deliveries](https://developer.fl3xx.com/reference/v2/webhooks/getwebhookdeliveries.md): Retrieve paginated webhook delivery history for the authenticated partner and operator.

Note: Only failed deliveries are supported at this time.

Features:
- Returns paginated delivery history with filtering and sorting
- Supports filtering by issue date and status
- Default sorting by issue date (descending)
 
Example Use Case: An operations manager needs to monitor webhook delivery to troubleshoot failed deliveries. Using this endpoint, they can review delivery history and identify patterns in webhook failures.