Supply Chain Disruption Monitoring: Build Alerts with FreightPulse API

March 16, 2026 · 10 min read · By FreightPulse Engineering

The Ever Given blocked the Suez Canal for six days in 2021 and cost global trade an estimated $9.6 billion per day. The Red Sea crisis rerouted 90% of container traffic around the Cape of Good Hope. COVID-19 shut down ports across Asia for weeks.

Supply chain disruptions aren't edge cases — they're constants. The question isn't whether disruptions will happen, but whether your system will detect them fast enough to act.

The Cost of Late Detection

Most logistics teams learn about disruptions from the news — hours or days after they begin. By then, rates have already spiked, capacity is booked, and alternative routes are scarce. Early detection gives you a critical window to:

• Reroute shipments before alternative capacity fills up
• Lock in rates before panic pricing takes hold
• Notify customers proactively instead of reactively
• Adjust inventory by accelerating or delaying orders

The difference between knowing about a disruption 6 hours early versus learning from a news headline can save tens of thousands of dollars per shipment.

What the Disruptions API Returns

FreightPulse's /v1/disruptions endpoint aggregates disruption data from multiple sources — weather services, port authorities, carrier announcements, geopolitical risk feeds, and labor union communications. Here's what a query looks like:

curl https://freightpulsehq.com/api/v1/disruptions \
  -H "X-API-Key: your_api_key" \
  -G \
  -d "severity=high,critical" \
  -d "region=asia-pacific"

Sample response:

{
  "disruptions": [
    {
      "id": "dis_2026_0316_001",
      "type": "weather",
      "severity": "high",
      "title": "Typhoon Warning: South China Sea",
      "description": "Category 3 typhoon expected to impact 
        Shenzhen and Hong Kong ports within 48 hours",
      "affected_ports": ["CNSZX", "HKHKG"],
      "affected_routes": ["CNSHA-USLAX", "CNSZX-NLRTM"],
      "estimated_delay_hours": 72,
      "started_at": "2026-03-16T08:00:00Z",
      "expected_resolution": "2026-03-19T00:00:00Z",
      "confidence": 0.85,
      "sources": ["JMA", "NOAA", "port_authority"]
    }
  ],
  "total": 1,
  "updated_at": "2026-03-16T14:30:00Z"
}

Disruption Categories

The API classifies disruptions into six categories, each requiring different response strategies:

• Weather — Typhoons, hurricanes, extreme fog, ice. Usually predictable 48-72 hours ahead.
• Labor — Port worker strikes, trucker protests, customs slowdowns. Often signaled by union negotiations weeks in advance.
• Geopolitical — Sanctions, trade route closures, military conflicts. High impact, harder to predict.
• Infrastructure — Canal blockages, bridge collapses, terminal fires. Sudden onset, variable recovery time.
• Regulatory — New customs requirements, inspection mandates, environmental regulations. Usually announced in advance.
• Capacity — Vessel blank sailings, equipment shortages, port capacity limits. Often cyclical and seasonal.

Building an Alert System

Step 1: Define Alert Rules

Not every disruption matters to every user. Build a rule engine that matches disruptions to user preferences:

// Example alert rule
const alertRules = [
  {
    user_id: "usr_123",
    routes: ["CNSHA-USLAX", "CNSHA-NLRTM"],
    ports: ["USLAX", "CNSHA"],
    min_severity: "medium",
    channels: ["email", "slack"]
  }
];

Step 2: Poll or Subscribe

You have two options for getting disruption data:

Polling: Hit the /v1/disruptions endpoint every 15-30 minutes. Simple to implement, works on all plans.

Webhooks: Register a webhook URL and receive instant notifications when new disruptions are detected or existing ones are updated. Available on Pro plans and above.

# Register a disruption webhook
curl -X POST https://freightpulsehq.com/api/v1/webhooks \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "disruption_created",
    "severity": ["high", "critical"],
    "url": "https://your-app.com/webhooks/disruptions"
  }'

Step 3: Enrich with Context

A disruption alert is more useful when it includes impact analysis. Combine disruption data with other FreightPulse endpoints:

• Fetch current freight rates for affected routes to show cost impact
• Check port congestion at alternative ports to suggest rerouting options
• Pull historical disruption data to estimate resolution timelines based on similar past events

Severity Scoring and Prioritization

FreightPulse uses a four-level severity scale:

• Low — Minor delays expected (<24 hours). Informational only.
• Medium — Moderate impact (24-72 hours). Monitor and plan contingencies.
• High — Significant disruption (72+ hours). Active rerouting recommended.
• Critical — Route closure or major infrastructure failure. Immediate action required.

Each disruption also includes a confidence score (0.0-1.0) indicating data reliability. Weather disruptions typically score 0.8+ (well-modeled), while geopolitical risks might score 0.5-0.7 (more uncertain).

Tracking Disruption Lifecycle

Disruptions aren't binary — they evolve. A strike might escalate from threatened to active to resolved. The API tracks this lifecycle with status fields:

• forecasted — Disruption predicted but not yet confirmed
• active — Currently impacting operations
• resolving — Impact diminishing, operations recovering
• resolved — Disruption over, normal operations resumed

Subscribe to status change webhooks to keep your users informed throughout the disruption lifecycle — not just at the start.

Building a Disruption Dashboard

A visual disruption dashboard is one of the highest-value features you can offer. Key components:

1. Global map view — Plot active disruptions geographically with severity-colored markers
2. Timeline view — Show disruptions on a timeline with estimated resolution dates
3. Impact analysis — For each disruption, show affected routes, estimated delays, and rate impacts
4. Historical patterns — Overlay past disruptions to show seasonal and recurring patterns

The /v1/disruptions/history endpoint provides historical data that makes the pattern analysis possible — helping users anticipate disruptions, not just react to them.

Getting Started

Disruption monitoring is available on all FreightPulse plans. The free tier lets you prototype your alert system with 100 API calls/month. Webhooks are available on Pro ($99/month) and above.

Check the API documentation for the complete disruptions endpoint reference.