Webhooks

A webhook is an HTTPS endpoint of yours that DisruptAPI calls when a signal matching your filters is created, escalates, changes or resolves. Each delivery is a signed JSON POST. This page covers events and payloads, signature verification, retries, deduplication and testing.

Create a webhook#

Send the URL and optional filters. You can also create webhooks in the console. Webhooks need a paid plan: Starter allows 3 active webhooks, Pro 20, Enterprise 100.

Request
curl -X POST "https://app.disruptapi.com/v1/webhooks" \
  -H "Authorization: Bearer $DISRUPT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/webhooks/disrupt",
  "filters": {
    "types": ["aviation", "weather"],
    "min_severity": "severe",
    "airports": ["SEA", "PDX"],
    "events": ["created", "escalated", "resolved"]
  }
}'
Response (201)JSON
{
  "data": {
    "id": "whk_8d2c41f0a6b9e357",
    "org_id": "org_5c1f0a9e2b7d4c31",
    "url": "https://example.com/webhooks/disrupt",
    "secret": "whsec_3b9f0c5e1a7d2846f0b3c9e1a5d7f2b4c6e8a0d1f3b5c7e9",
    "filters": {
      "airports": ["PDX", "SEA"],
      "events": ["created", "escalated", "resolved"],
      "min_severity": "severe",
      "types": ["aviation", "weather"]
    },
    "created_at": "2026-11-18T08:05:40Z"
  }
}

URL rules#

  • https only, on port 443 or 8443, at most 500 characters, with no user name or password in the URL.
  • The host must resolve only to public addresses. Private, loopback, link-local and carrier-grade NAT ranges are refused. This is checked when you create the webhook and again before every delivery.
  • A refused URL returns 400 invalid_webhook with the reason.

Filters#

All filters you set must match (AND). Inside a list, any value can match (OR). No filters means every signal change. Lists hold at most 500 entries; unknown filter keys are ignored.

FilterTypeDescription
typesstring[]Signal types, e.g. ["aviation", "weather"].
min_severitystringminor, moderate, severe or extreme: only signals at or above it.
countriesstring[]ISO alpha-2 codes; the signal must cover at least one.
airportsstring[]IATA codes; the signal must list at least one.
carriersstring[]IATA airline codes. Matches IT outages that put one of these airlines at medium or high risk. Other signal types never match this filter.
eventsstring[]Any of created, escalated, updated, resolved. Default: all four.
watchlistsstring[]["*"] for all your watchlists, or watchlist ids. Only signals that touch an item on them fire, and the payload becomes an exposure.* event listing those items.

With watchlists, item matching uses every severity, so min_severity on the webhook is what limits severity. For resolutions, items are matched against the signal's last known footprint, so you hear when a disruption that touched your items ends.

Which events are there?#

TypeWhen
signal.createdA new signal, or a resolved one that came back.
signal.escalatedSeverity went up, or more airports are affected.
signal.updatedAnother material change: severity down, title, countries, airports, end time, failure layer.
signal.resolvedThe source no longer lists it, or its end time passed.
exposure.created, .escalated, .updated, .resolvedThe same four events, for webhooks with a watchlists filter, when the signal touches at least one of your watched items.

Changes that are not material (new wording in details, a different area list) do not fire. See the signal lifecycle.

What does a delivery contain?#

A POST with a UTF-8 JSON body: id (evt_ plus 16 hex characters), type, created_at and data. For signal.* events, data is the signal. For exposure.* events, data holds the signal and the exposed_items. IT outage signals include impact_forecast.

Payload
{
  "id": "evt_5f1c9a0b2d7e4c83",
  "type": "signal.escalated",
  "created_at": "2026-11-18T07:21:15Z",
  "data": {
    "id": "faa_ground_stop_SEA.k3j9x2m1qa",
    "type": "aviation",
    "subtype": "ground_stop",
    "provider": "faa",
    "failure_layer": null,
    "failure_layer_label": null,
    "title": "Ground Stop Program at SEA: low ceilings",
    "severity": "severe",
    "status": "active",
    "countries": ["US"],
    "airports": ["SEA"],
    "areas": [],
    "location": { "lat": 47.449, "lon": -122.309 },
    "starts_at": null,
    "ends_at": null,
    "first_seen_at": "2026-11-18T06:52:10Z",
    "updated_at": "2026-11-18T07:20:41Z",
    "version": 2,
    "source": {
      "url": "https://nasstatus.faa.gov/",
      "attribution": "FAA NAS Status",
      "last_checked_at": "2026-11-18T07:21:02Z",
      "stale": false
    },
    "details": { "reason": "low ceilings", "End_Time": "8:30 am PST" }
  }
}
HeaderValue
Content-Typeapplication/json
Disrupt-Signaturet=<unix seconds>,v1=<hex HMAC-SHA256>. See verification.
Disrupt-Webhook-IdThe webhook's id, whk_.... Useful when several webhooks point at one URL.
User-AgentDisruptAPI-Webhooks/1.0

How do I verify the signature?#

Every delivery is signed with your webhook's secret. Verify before you parse or act on the body.

  1. Read the Disrupt-Signature header and split it on commas into t (Unix seconds) and v1 (lowercase hex).
  2. Reject the request if t is more than 5 minutes from your clock. This stops replays of old deliveries.
  3. Compute HMAC-SHA256 with the whole secret, including the whsec_ prefix, as the key, over the bytes t, then ., then the raw request body.
  4. Compare your hex digest with v1 in constant time.
Verify Disrupt-Signature
// Node.js 18+ with Express 4 or 5. npm install express
import crypto from "node:crypto";
import express from "express";

const SECRET = process.env.DISRUPT_WEBHOOK_SECRET; // whsec_..., shown once when the webhook was created

export function verifyDisruptSignature(secret, rawBody, header, toleranceSec = 300) {
  if (!header) return false;
  let t, v1;
  for (const part of header.split(",")) {
    const i = part.indexOf("=");
    if (i < 0) return false;
    const key = part.slice(0, i).trim();
    const value = part.slice(i + 1).trim();
    if (key === "t") t = value;
    if (key === "v1") v1 = value;
  }
  const ts = Number.parseInt(t ?? "", 10);
  if (!Number.isSafeInteger(ts) || !v1) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - ts) > toleranceSec) return false;

  // Signed content: "<t>." followed by the raw request body, exactly as received.
  const expected = crypto.createHmac("sha256", secret).update(`${ts}.`).update(rawBody).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(v1);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

const app = express();

// express.raw keeps the body as a Buffer. Do not parse JSON before verifying.
app.post("/webhooks/disrupt", express.raw({ type: "application/json" }), (req, res) => {
  if (!verifyDisruptSignature(SECRET, req.body, req.get("Disrupt-Signature"))) {
    return res.status(400).send("bad signature");
  }
  const event = JSON.parse(req.body.toString("utf8"));
  res.status(204).end(); // answer fast, then do the work
  console.log(event.type, event.data.signal?.id ?? event.data.id);
});

app.listen(3000);

Retries and disabling#

A delivery succeeds when your endpoint answers with any 2xx status within 10 seconds. Redirects are not followed and count as failures, as do timeouts, connection errors and other statuses. Only the first 64 KB of your reply is read.

AttemptSent
1When the change is detected
21 minute after attempt 1 fails
35 minutes after attempt 2
430 minutes after attempt 3
52 hours after attempt 4
66 hours after attempt 5; if it fails, the delivery is marked failed and not retried

Deliveries are sent by a background loop, so times are approximate. A webhook whose deliveries fail 50 times in a row, counting every attempt, is disabled; any success resets the count. A disabled webhook gets no more deliveries, shows disabled_at in GET /v1/webhooks and no longer counts against your plan. There is no re-enable call: fix the endpoint and create a new webhook.

Idempotency and ordering#

Plan for duplicates and for deliveries arriving out of order:

  • Do not deduplicate on the event id. The payload is built when each attempt is sent, so a retry carries a new id, a new created_at and a new signature.
  • The payload holds the signal as it is when the attempt is sent, which can be newer than the change that queued it. A retried signal.escalated can arrive with a later version.
  • Deduplicate on the signal id and version. Keep the highest version you have processed for each signal id and ignore payloads at or below it. Each webhook gets at most one delivery per signal version.
  • Order is not guaranteed across signals or across retries. Use version (or updated_at) to decide which state is newest.
Deduplicate by versionNode.js
// Keep the highest version you have processed per signal. Ignore anything older or equal.
async function handle(event, store) {
  const signal = event.type.startsWith("exposure.") ? event.data.signal : event.data;
  const seen = await store.getVersion(signal.id); // null if never seen
  if (seen !== null && signal.version <= seen) return; // duplicate or out of order
  await store.saveSignal(signal);                     // upsert by signal.id
  await store.setVersion(signal.id, signal.version);
  if (event.type.startsWith("exposure.")) await notifyOwners(event.data.exposed_items, signal);
}

Answer quickly. Return 2xx as soon as the signature checks out, and do slow work (emails, rebooking logic) in a queue. A handler that takes longer than 10 seconds is treated as failed and the delivery is retried.

How do I test webhooks locally?#

DisruptAPI only delivers to public HTTPS addresses, so localhost cannot be registered directly. There is no endpoint that sends a test event. Two ways to test:

  1. Unit-test your handler with a signed sample. Sign a body yourself with your secret and post it to your local server. If your code accepts this, it accepts real deliveries.
  2. End to end through a tunnel. Run an HTTPS tunnel that gives your local port a public address on port 443, register that URL as a webhook (with broad filters, for example {"min_severity": "minor"}), and wait for the next signal change. Delete the webhook afterwards.
Sign a test deliveryShell
# Send a correctly signed test event to your local handler.
SECRET="whsec_your_test_secret"
BODY='{"id":"evt_test0000000001","type":"signal.created","created_at":"2026-11-18T08:00:00Z","data":{"id":"test.signal","version":1}}'
T=$(date +%s)
SIG=$(printf '%s.%s' "$T" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.* //')

curl -i http://localhost:3000/webhooks/disrupt \
  -H "Content-Type: application/json" \
  -H "Disrupt-Signature: t=$T,v1=$SIG" \
  --data-raw "$BODY"

List and delete webhooks#

List
curl "https://app.disruptapi.com/v1/webhooks" \
  -H "Authorization: Bearer $DISRUPT_KEY"

The list includes disabled webhooks with their disabled_at time and failures count. Deleting a webhook disables it at once; pending deliveries are not sent.

Delete
curl -X DELETE "https://app.disruptapi.com/v1/webhooks/whk_8d2c41f0a6b9e357" \
  -H "Authorization: Bearer $DISRUPT_KEY"

Last updated 2026-11-18. Questions or a mistake on this page? Contact us.