Best practices
These are the patterns that keep an integration correct and inside its limits: when to poll and when to use webhooks, how to deduplicate, what to cache, how to treat stale sources, and how to set timeouts and retries.
Should I poll or use webhooks?#
| Need | Use |
|---|---|
| Know when a disruption touches one of your bookings, places or suppliers | A watchlist plus a webhook with "watchlists": ["*"] |
| React to new or changing disruptions in an area or category | A webhook with types, countries, airports or min_severity filters |
| Answer a question now, e.g. at booking time or in a support tool | POST /v1/exposure/check |
| Keep a local copy of signals for analytics or your own UI | Poll GET /v1/signals?status=all&since=... every few minutes |
| Sandbox plan, or no public HTTPS endpoint | Poll with since; webhooks need a paid plan and a public URL |
Webhooks save requests and arrive soon after a change is detected. Polling is simpler to run and to replay. Many integrations use both: webhooks for alerts, plus a slow poll (every 15 to 60 minutes) as a safety net in case deliveries fail.
How do I deduplicate?#
Use the signal id plus version. A signal at the same version has not changed materially. Keep the highest version per id and ignore anything at or below it.
- Do not deduplicate webhook events on the event
id; it changes on every delivery attempt. See idempotency. - Polling with
sincereturns the boundary signal again; the version check skips it. - Do not use
titleor timestamps as keys. Titles can change, andupdated_atis not unique. - Store signal ids as returned to your key. They are specific to your organisation.
What can I cache?#
| Data | Cache for |
|---|---|
GET /v1/failure-layers, GET /v1/plans | A day or more; they rarely change |
GET /v1/sources, GET /v1/events | An hour to a day |
| Airport and carrier profiles | Minutes; they include active signals |
GET /v1/forecast | An hour or so; numbers move as the catalogue grows |
| Signals and exposure results | Do not cache beyond a few minutes; update from webhooks or since polls |
API responses are sent with Cache-Control: no-store, so caching is your choice in your own layer, not something HTTP caches do for you. Cache by the full request (path, query and body), since results depend on filters and plan.
How should I handle stale sources?#
When source.stale is true, DisruptAPI has not been able to read that source recently. The signal is shown as last seen, and it may have changed or ended.
- Keep showing active signals from stale sources, with a note. Hiding them can hide a real disruption.
- Do not treat "no signals" as "all clear" for an area whose main source is stale. Check
GET /v1/sources. - For automated decisions (rebooking, refunds), require a fresh source or a human check.
// Show a signal with an honest freshness note.
function freshnessNote(signal, now = Date.now()) {
const { last_checked_at, stale } = signal.source;
if (!stale) return null;
if (!last_checked_at) return "Source not reachable; this may be out of date.";
const mins = Math.round((now - Date.parse(last_checked_at)) / 60000);
return `Source last checked ${mins} min ago; this may have changed or ended.`;
}Timeouts and retries#
- Set a client timeout of about 30 seconds. Large exposure checks take longer than single lookups.
- Retry only what can succeed:
429 rate_limitedafterRetry-After,5xxand network errors with exponential backoff and jitter, at most a few times. Do not retry other4xxerrors. See which errors to retry. - Retry writes safely. Adding watchlist items is idempotent by item
id. Creating a watchlist or webhook is not; list first if a create timed out. - Webhook handlers: answer
2xxwithin 10 seconds and move work to a queue.
Keep watchlists in sync with your bookings#
Send items when a booking is created or changed, with your booking reference as id. Cancelled bookings: remove the item with DELETE /v1/watchlists/{id}/items/{ref}, or let flights and trips expire a day after they end. Batch up to 1,000 items per call.
// Push bookings into a watchlist as they change. Re-sending the same id replaces the item.
async function syncBookings(watchlistId, bookings) {
const items = bookings.map((b) => ({
id: b.reference, // your stable id
kind: "flight",
carrier: b.carrier,
origin: b.from,
destination: b.to,
depart_at: b.departUtc, // "2026-12-03T06:40:00Z"
arrive_at: b.arriveUtc,
customer_id: b.customerId, // your own metadata is stored with the item
}));
for (let i = 0; i < items.length; i += 1000) {
const res = await fetch(`https://app.disruptapi.com/v1/watchlists/${watchlistId}/items`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.DISRUPT_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ items: items.slice(i, i + 1000) }),
signal: AbortSignal.timeout(30_000),
});
if (!res.ok) throw new Error(`${res.status} ${(await res.json()).error?.code}`);
}
}Use fewer requests and records#
- Check many items in one exposure call (up to 500) rather than one call per item.
- Filter list calls (
type,country,airport,min_severity,since) instead of reading everything and filtering locally. Records count against a daily budget. - Watch
X-RateLimit-Remaining,X-Quota-RemainingandX-Data-Records-Remaining-Today, and alert before they reach zero.
Show results to people honestly#
- Say when a match is country-level only (the reason says "placed at country level" or "covers XX").
- Label news-derived signals as reports, not official warnings.
- DisruptAPI does not know whether a specific flight will operate. Point travellers to their airline for flight status.
Last updated 2026-11-18. Questions or a mistake on this page? Contact us.