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?#

NeedUse
Know when a disruption touches one of your bookings, places or suppliersA watchlist plus a webhook with "watchlists": ["*"]
React to new or changing disruptions in an area or categoryA webhook with types, countries, airports or min_severity filters
Answer a question now, e.g. at booking time or in a support toolPOST /v1/exposure/check
Keep a local copy of signals for analytics or your own UIPoll GET /v1/signals?status=all&since=... every few minutes
Sandbox plan, or no public HTTPS endpointPoll 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 since returns the boundary signal again; the version check skips it.
  • Do not use title or timestamps as keys. Titles can change, and updated_at is not unique.
  • Store signal ids as returned to your key. They are specific to your organisation.

What can I cache?#

DataCache for
GET /v1/failure-layers, GET /v1/plansA day or more; they rarely change
GET /v1/sources, GET /v1/eventsAn hour to a day
Airport and carrier profilesMinutes; they include active signals
GET /v1/forecastAn hour or so; numbers move as the catalogue grows
Signals and exposure resultsDo 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.
Freshness noteNode.js
// 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_limited after Retry-After, 5xx and network errors with exponential backoff and jitter, at most a few times. Do not retry other 4xx errors. 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 2xx within 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.

Sync bookingsNode.js
// 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-Remaining and X-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.