How to build a flight delay notification system. A developer tutorial for building flight delay and status-change alerts using a webhook-based flight alert API — subscriptions, change handling, notification thresholds and architecture.
A flight delay notification system watches a set of flights and tells users when something changes — a delay, a gate change, a new estimated arrival time, a diversion. It is one of the most requested features in travel products, and for good reason: a timely "your flight is now delayed 40 minutes, gate changed to B22" is exactly the kind of proactive help that makes users trust an app.
This tutorial walks through how to build such a system as a developer. It covers the architecture, the subscription model, how to handle changes without spamming users, and the practical concerns of running it in production. The examples use the AirLabs Flight Alert API, which is designed specifically for this — a webhook-based approach that pushes changes to your server rather than making you ask for them repeatedly.
One thing to be clear about up front, because it affects the design: the Flight Alert API is currently in Beta, and early access is available on paid plans. This guide is written for teams building a production notification system, where that is the normal starting point.
"The naive way to build delay alerts is to ask the API 'anything new?' every few minutes, forever. The better way is to let the API tell you the moment something changes. That single architectural choice — push instead of poll — is what separates an efficient notification system from one that burns resources checking flights that have not moved."
Before any code, the most important decision is how your system learns that a flight changed. There are two models, and they lead to very different systems.
The polling model has your server repeatedly call a status endpoint — every five minutes, say — for every flight it is watching, comparing each response to the last to detect changes. This works, but it scales badly. You make constant requests whether or not anything changed, most of which return nothing new. As the number of watched flights grows, so does the request volume, and much of it is wasted on flights sitting quietly at their scheduled time.
The webhook (push) model inverts this. You tell the API which flights to watch and give it a URL on your server. The API monitors those flights and sends a request to your URL only when something actually changes. Your server sits idle until there is real news, then reacts. This is the model the AirLabs Flight Alert API uses, and it is the more efficient foundation for a notification system: you are not paying, in requests or compute, to check flights that have not moved.
The rest of this tutorial builds on the webhook model, because it is both simpler to reason about and more efficient to run.
You start watching a flight by creating a subscription — a "listener" — through the Listen API. You specify which flights to watch using filters, and a webhook_url on your server where updates should be sent:
GET https://airlabs.co/api/v9/listen?flight_iata=AA6&webhook_url=https://your-server.com/hook&api_key={KEY}The API creates the listener and returns its ID:
{ "listener_id": 99 }Store that listener_id — you will need it to stop the subscription later. The filters let you scope exactly what to watch. You can listen by flight (airline_iata + flight_number), by departure or arrival airport (dep_iata, arr_iata), by date (dep_date, arr_date), and more. So you can watch a single passenger's flight, or every departure from a given airport, depending on your product.
There is one more useful parameter: _fields. By default the listener reports all changes, but you can narrow it to specific fields — for example only status, dep_delayed, arr_delayed, dep_gate, arr_estimated. Narrowing the fields is not just tidiness; as discussed below, it directly controls how often your server is called, which matters for both noise and quota.
When a watched flight changes, the API sends a request to your webhook_url. The payload is the heart of the system: it tells you exactly what changed and gives you the flight's full current state.
{
"listener_id": 4397,
"changed": [
"dep_gate", "dep_estimated", "status", "dep_delayed", "arr_delayed"
],
"flight": {
"flight_iata": "AA1",
"status": "active",
"dep_iata": "JFK",
"dep_gate": "39",
"arr_iata": "LAX",
"arr_gate": "46C",
"arr_estimated": "2021-08-12 11:12",
"dep_delayed": null,
"arr_delayed": 2
}
}The changed array is what makes this powerful. Rather than handing you a new state and leaving you to diff it against the old one, the API tells you precisely which fields moved — here, the gate, the estimated departure, the status and the delay figures. This lets you craft a specific, meaningful notification instead of a vague "something updated." If dep_gate is in changed, you send "gate changed to 39"; if arr_delayed is in changed, you send "arriving 2 minutes late." The full flight object gives you all the current values to build the message from.
A small but important detail from the documentation: the top-level delayed field is deprecated — use dep_delayed and arr_delayed instead, which distinguish a departure delay from an arrival delay. Building on the deprecated field would be a mistake that is easy to avoid if you know about it.
Your webhook handler, then, does three things: verify the request is legitimate, look at changed to decide what happened, and decide whether it is worth notifying the user. That last decision is where a good system differs from a noisy one.
This is the part that separates a notification system users trust from one they mute. Not every change deserves a push. Estimated times in particular can update repeatedly by a minute or two, and firing a notification on every one of those is exactly how you train users to ignore your alerts.
A few controls keep notifications meaningful:
_fields on the listener so you are only told about the changes you care about. If gate changes and delays matter but tiny estimated-time wiggles do not, listen for the former and not the latter. This is the cheapest filter, because a change you never receive costs you nothing to handle.arr_delayed/dep_delayed against what you last told the user, and only notify when the difference crosses your threshold.status change to cancelled or diverted, for instance. Treat these as override events.The underlying principle: update your interface often, but interrupt the user rarely. Your app's screen can reflect every webhook; a push notification should only fire when the change actually affects what the user might do.
A flight's relevance ends — it lands, or the user cancels their subscription. When it does, you remove the listener with the Unlisten API, using the listener_id you stored earlier:
GET https://airlabs.co/api/v9/unlisten?listener_id=99&api_key={KEY}{ "unlistened": true }Cleaning up finished listeners is not just tidiness — because each webhook counts against your quota (below), leaving stale listeners running is a direct waste. A well-built system removes a listener as soon as the flight lands or the user unsubscribes. You can also retrieve all your active listeners with the Listeners API (/listeners) to audit what you are currently watching, which is useful for reconciling state after a restart.
Moving from a working prototype to a production system brings a few concrete operational details, and the Flight Alert API documentation is explicit about them — worth building in from the start rather than discovering later.
Webhooks count against your quota. Each webhook request sent to your server is subtracted from your account's total request quota. This is the single most important operational fact for a notification system, and it directly rewards good design: the tighter your filters and thresholds, the fewer unnecessary webhooks you receive, and the less quota you burn. A listener watching all changes on a busy airport will generate far more webhook traffic — and quota usage — than one watching a single flight's status and arr_delayed. Set filters carefully; it is both a user-experience decision and a cost decision.
Whitelist the webhook source IPs. The API sends webhooks from a specific set of server IP addresses, which the documentation provides and recommends you whitelist in your systems. Because these can change, the guidance is to keep an up-to-date list rather than hard-coding it once. Building your ingress to accept the current published IPs protects your endpoint and ensures you keep receiving webhooks reliably.
Design your webhook endpoint defensively. Standard webhook-handling practice applies: respond quickly (do the heavy work asynchronously so you acknowledge the webhook fast), and make your processing idempotent so that a repeated delivery does not double-notify a user. The Webhooks History method (/webhooks) lets you retrieve the history of webhooks sent to your server, including the response status your endpoint returned — useful for debugging deliveries and confirming your handler is accepting them.
Putting the pieces together, a flight delay notification system on this model has a clear shape:
webhook_url, and stores the returned listener_id against that user.changed array, applies your thresholds and dedup logic, and — when warranted — sends the user a specific notification.listener_id to stop watching and stop consuming quota.Everything else — the push notification transport, the user database, the UI — is your application's own infrastructure. The flight-data side reduces to those three interactions plus a well-designed webhook handler. That is the whole system, and it is deliberately small because the push model does the watching for you.
_fields to listen only for what you notify on — a change you do not receive is one you never have to filter out later, and it does not cost quota.dep_delayed/arr_delayed, not the deprecated delayed — and distinguish departure from arrival delays in your messaging.If you are building flight delay or status-change notifications, the AirLabs Flight Alert API provides the webhook-based foundation — subscriptions by flexible filters, precise change reporting, and the operational controls a production system needs. For understanding the delay data itself, see Flight Delay Data Explained; for the broader business context of flight monitoring, see Real-Time Flight Tracking for Business.
Our Developer API allows you to create a custom experience for your users and increase the value of your product:
_fields to scope which changes are reported.changed array identifying exactly which fields moved, plus the full current flight state.dep_delayed and arr_delayed fields, status, gate, terminal and estimated times for building precise notifications.You can try it right now! Get a free flight API plan to explore the data, and a paid plan for Alert API beta access.
If you need more information, don't hesitate to contact us. We are always happy to chat with our customers and are sure to find a customized solution for each request.
Explore AirLabs, or create an account instantly and start using API.
Get FREE API Key