> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flyhub.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Virtual Airlines Webhooks

> Send airline activity notifications to Discord and understand every event, payload, and delivery rule.

# Virtual Airlines Webhooks

Virtual Airlines webhooks send selected airline activity to a Discord channel. They are useful for an operations room, pilot community, management team, or live airline activity feed.

Discord is the supported destination. FlyHub sends formatted messages asynchronously; it does not send a generic JSON callback to an arbitrary URL, and it does not provide an inbound webhook that your website can call.

Each event below includes the information you can expect to see in Discord. Use this guide to set up a destination, choose events, and understand delivery.

## What you can build

With a Discord destination, an airline can announce:

* flight bookings, cancellations, completions, rejections, and settlements;
* pilot applications and membership decisions;
* pilots joining, leaving, being suspended, restored, removed, or changing roles;
* fleet changes and schedule changes;
* published airline announcements.

If you need a website, dashboard, or private service to read airline data, use the [Virtual Airlines API Reference](./api-reference). Webhooks are notifications, not a replacement for the API.

## Set up a Discord destination

From FlyHub:

1. Open the airline in **Airlines**.
2. Open **Manage airline**.
3. Select **Ownership**.
4. Open **Integrations** and choose the Discord webhook option.
5. Give the destination a name that tells managers where it goes, such as `Operations room` or `Pilot announcements`.
6. Paste a Discord webhook URL and choose one or more event types.
7. Save it, then use **Test** before relying on it for operations.

Only an airline owner or manager with access to Integrations can create, list, edit, test, pause, resume, or remove destinations.

### Accepted Discord URLs

FlyHub accepts only an HTTPS Discord webhook URL with this structure:

```text theme={null}
https://discord.com/api/webhooks/<numeric-id>/<token>
https://www.discord.com/api/v10/webhooks/<numeric-id>/<token>
https://discordapp.com/api/webhooks/<numeric-id>/<token>
```

The exact rules are:

* protocol must be `https`;
* host must be exactly `discord.com`, `www.discord.com`, or `discordapp.com`;
* the path must be `/api/webhooks/...` or `/api/vN/webhooks/...`;
* the webhook ID must contain 5–30 digits;
* the token must contain 20–200 letters, numbers, dots, underscores, or hyphens;
* a trailing slash is allowed;
* query strings and fragments are removed before storage.

FlyHub rejects look-alike domains, HTTP URLs, local addresses, redirects, and arbitrary external endpoints. This keeps notifications limited to the Discord destination you selected.

Treat a Discord webhook URL like a password. Anyone who obtains the complete URL can post to that Discord destination. FlyHub shows managers only a preview after creation, such as `discord.com/api/webhooks/…123456`.

An airline can have up to 10 active or paused destinations. A removed or automatically disabled destination does not count toward that active limit, but it cannot be restored; create a new destination from Integrations instead.

## Manage destinations

Owners and authorized managers can manage Discord destinations from **Manage airline → Ownership → Integrations**. From there you can list destinations, create one, choose its events, send a test, pause or resume it, and remove it.

After a destination is created, FlyHub shows only a safe preview of its URL. If the URL changes, create and test the replacement before removing the old destination. A removed or disabled destination cannot be restored from the page.

The event examples below show the kind of notification that can appear in Discord.

## Event catalog

FlyHub maps selected airline activity to public event names. The event name is included in every normal Discord embed as an `Event` field.

| Event | Group | When it is sent | Common information |
| - | - | - | - |
| `flight.booked` | Flights | A flight booking is recorded. | Status, flight number, route, aircraft, pilot, tracking mode, and load when available. |
| `flight.cancelled` | Flights | A flight instance is cancelled. | State, reason, flight number, route, aircraft, and planned times when available. |
| `flight.completed` | Flights | A flight result is accepted. | Result classification, route, aircraft, pilot, tracking, load, distance, block time, landing rate, score, and settlement context when available. |
| `flight.rejected` | Flights | A flight result is rejected. | Result classification, rejection reason, route, aircraft, pilot, performance, and score when available. |
| `pilot.applied` | Pilots | A pilot application is received and remains pending. | Display name, membership status, rank, and FlyHub totals when available. |
| `pilot.joined` | Pilots | A pilot becomes active in the airline. | Display name, active status, rank, and FlyHub totals when available. |
| `pilot.rejected` | Pilots | An application or membership is rejected. | Display name, status, and rank when available. |
| `pilot.suspended` | Pilots | An active pilot is suspended. | Display name, status, rank, and FlyHub totals when available. |
| `pilot.restored` | Pilots | A suspended pilot becomes active again. | Display name, status, rank, and FlyHub totals when available. |
| `pilot.left` | Pilots | A pilot leaves the airline. | Display name, status, rank, and FlyHub totals when available. |
| `pilot.removed` | Pilots | A manager removes a pilot. | Display name, status, rank, and FlyHub totals when available. |
| `pilot.role_changed` | Pilots | A pilot's airline role changes. | Display name, status, rank, and the public role-change summary when available. |
| `fleet.changed` | Operations | An aircraft or its operating state changes. | Registration, type, ownership, station, status, condition, maintenance state, hours, and cycles. |
| `schedule.changed` | Operations | A published route or schedule changes. | Flight number, route, operation type, operating days, block time, eligible aircraft, and status. |
| `finance.flight_settled` | Operations | A flight settlement is recorded. | Flight context when available, net result, and currency. |
| `announcement.published` | Community | Airline content is published. | Content kind, version, and publication status. |

The same action can produce a different public event depending on the resulting state. For example, a membership application that is immediately accepted can produce `pilot.joined`, while a pending application produces `pilot.applied`.

### Event examples

| Event | Payload reference |
| - | - |
| `flight.booked` | [flight.booked](https://docs.flyhub.app/virtual-airlines/api/webhooks/flight-booked) |
| `flight.cancelled` | [flight.cancelled](https://docs.flyhub.app/virtual-airlines/api/webhooks/flight-cancelled) |
| `flight.completed` | [flight.completed](https://docs.flyhub.app/virtual-airlines/api/webhooks/flight-completed) |
| `flight.rejected` | [flight.rejected](https://docs.flyhub.app/virtual-airlines/api/webhooks/flight-rejected) |
| `pilot.applied` | [pilot.applied](https://docs.flyhub.app/virtual-airlines/api/webhooks/pilot-applied) |
| `pilot.joined` | [pilot.joined](https://docs.flyhub.app/virtual-airlines/api/webhooks/pilot-joined) |
| `pilot.rejected` | [pilot.rejected](https://docs.flyhub.app/virtual-airlines/api/webhooks/pilot-rejected) |
| `pilot.suspended` | [pilot.suspended](https://docs.flyhub.app/virtual-airlines/api/webhooks/pilot-suspended) |
| `pilot.restored` | [pilot.restored](https://docs.flyhub.app/virtual-airlines/api/webhooks/pilot-restored) |
| `pilot.left` | [pilot.left](https://docs.flyhub.app/virtual-airlines/api/webhooks/pilot-left) |
| `pilot.removed` | [pilot.removed](https://docs.flyhub.app/virtual-airlines/api/webhooks/pilot-removed) |
| `pilot.role_changed` | [pilot.role\_changed](https://docs.flyhub.app/virtual-airlines/api/webhooks/pilot-role-changed) |
| `fleet.changed` | [fleet.changed](https://docs.flyhub.app/virtual-airlines/api/webhooks/fleet-changed) |
| `schedule.changed` | [schedule.changed](https://docs.flyhub.app/virtual-airlines/api/webhooks/schedule-changed) |
| `finance.flight_settled` | [finance.flight\_settled](https://docs.flyhub.app/virtual-airlines/api/webhooks/finance-flight-settled) |
| `announcement.published` | [announcement.published](https://docs.flyhub.app/virtual-airlines/api/webhooks/announcement-published) |

## The Discord payload

These are Discord webhook messages, not a custom FlyHub JSON event protocol. FlyHub sends an HTTP `POST` to Discord with a JSON body containing a username, disabled mentions, and one embed.

Representative normal payload:

```json theme={null}
{
  "username": "EXA Operations",
  "allowed_mentions": {
    "parse": []
  },
  "embeds": [
    {
      "title": "✈️ EXA42 completed",
      "description": "The flight result was accepted in FlyHub.",
      "color": 2277190,
      "fields": [
        {
          "name": "🧭 Route",
          "value": "🇨🇴 **SKBO** — Bogotá\\n→ 🇺🇸 **KMIA** — Miami",
          "inline": false
        },
        {
          "name": "👨‍✈️ Pilot",
          "value": "Example Pilot",
          "inline": true
        },
        {
          "name": "🟩 Score",
          "value": "9.67 / 10",
          "inline": true
        },
        {
          "name": "Airline",
          "value": "Example Air (EXA)",
          "inline": true
        },
        {
          "name": "Event",
          "value": "flight.completed",
          "inline": true
        }
      ],
      "footer": {
        "text": "FlyHub • Event 12345"
      },
      "timestamp": "2026-07-21T12:00:00.000Z"
    }
  ]
}
```

A notification includes related flight, pilot, aircraft, schedule, settlement, or publication details when those details are available. If a detail is unavailable, FlyHub sends the event with the information it can show.

### Payload safety and size

* Discord mentions are disabled with `allowed_mentions.parse: []`, so airline text cannot accidentally ping everyone, a role, or a user.
* Only public airline and operation details are copied into the summary.
* A normal message contains one embed.
* At most 25 embed fields are included.
* Embed field names are capped at 256 characters and values at 1,024 characters.
* Long text is shortened when necessary so the message stays readable in Discord.
* The sender name is the airline ICAO code followed by `Operations`.

These notifications are intended for Discord. If your own service needs structured data, use the read-only VA API or your normal Discord tooling.

## Delivery behavior

Normal notifications are asynchronous. When a supported action occurs, FlyHub sends the matching notification to every active destination subscribed to that event. A destination must be active when the notification is processed; pausing a destination stops new notifications from being sent to it.

Temporary failures may be retried automatically. Delivery timing is not guaranteed, so use the event details rather than the arrival time when interpreting an update. If your Discord workflow triggers automation, make it tolerant of an occasional duplicate notification.

### Automatic destination disablement

Repeated delivery failures can automatically disable a destination. A disabled destination does not receive events and cannot be reactivated from the page; fix the Discord configuration and create a replacement. A paused destination can be resumed from Integrations.

### Duplicate tolerance

Notifications are not a guaranteed exactly-once stream. Your Discord workflow should tolerate an occasional duplicate and should avoid treating the arrival of a message as proof that a flight or membership action succeeded; use the event details and the FlyHub API when you need to verify state.

## What counts as a successful post

FlyHub sends a standard Discord webhook request with the payload described above. A notification is considered delivered when Discord accepts the request. If Discord or FlyHub is temporarily unavailable, the notification may be retried according to the delivery behavior above.

## Pause, resume, change, and rotate safely

### Temporary pause

Choose **Pause** on the destination.

Choose **Resume** when you want notifications to continue.

### Change the event list

Edit the destination and replace its event selection. The new selection becomes the complete subscription list.

### Change the Discord channel

Discord webhook URLs are not edited in place. Create the new destination, send a test, confirm the message arrived in the intended channel, then remove the old destination.

### Recover from automatic disablement

Inspect the preview, check the Discord channel and webhook permissions, create a new Discord webhook if necessary, then create a new FlyHub destination. A disabled destination is historical and cannot be reactivated.

## Troubleshooting

* If FlyHub rejects the URL, copy it again from Discord and confirm that it is an HTTPS Discord webhook URL.
* If **Test** fails, confirm that the Discord webhook still exists and that the destination channel accepts messages.
* If no notifications arrive, confirm that the destination is active and that the event is selected.
* If a destination is disabled after repeated delivery failures, create a replacement after checking the Discord channel and permissions.
* If FlyHub reports a temporary problem, wait a moment and retry from the Integrations screen. Do not create duplicates until you have confirmed the destination's current state.

## Limits and non-features

Discord notifications do not provide:

* arbitrary custom HTTP destinations;
* inbound webhooks into FlyHub;
* signed generic callbacks or a signing-secret configuration;
* a delivery-history page;
* replaying a past event;
* editing a Discord URL in place;
* restoring a removed or automatically disabled destination;
* complete private account records;
* guaranteed exactly-once delivery.

For structured, pull-based data, use the six read-only resources in the [Virtual Airlines API Reference](./api-reference). For live community notifications, use Discord as the supported webhook destination.

## Security checklist

* Keep the complete Discord URL private.
* Do not paste it into a public issue, screenshot, source file, or browser URL.
* Use a separate Discord webhook per channel or purpose so it can be revoked without disrupting every notification.
* Subscribe only to events the channel should receive.
* Test in a private operations channel before using a public community channel.
* Treat `disabled` as a configuration or delivery-health problem, not as a reason to bypass the safeguards.
* Remember that notifications may contain pilot display names, route information, scores, aircraft details, and financial net results. Choose the Discord channel's audience accordingly.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.