DISRUPTION_EVENT Callback

9 min

Overview

The DISRUPTION_EVENT callback notifies your system when a shipment disruption is detected, so you can react without polling the FourKites UI. FourKites pushes the event to your registered callback endpoint as soon as the disruption pipeline identifies an impact to a tracked shipment.

This callback is currently live for weather-related disruptions only (flood warnings, tornado warnings, and similar NOAA-classified alerts). Support for OTR, Rail, Ocean, and Air disruptions is planned for a future phase and will extend the same payload structure.

To receive this callback, your company must be subscribed via the Additional Subscribed Event configuration. Reach out to your FourKites CSM to have it enabled.

Sample Payload

{
  "AlertName": "Flood Warning",
  "DetectedAt": "2026-07-14T07:08:05Z",
  "DisruptionEndedAt": "2026-07-13T18:00:00+00:00",
  "DisruptionModes": [],
  "DisruptionStartedAt": "2026-07-13T10:00:00+00:00",
  "DisruptionType": "weather",
  "EventCategory": "Flood Warning",
  "EventType": "disruption.shipment.created",
  "FourKitesLoadId": 19959237,
  "LoadNumber": "test_callbacks",
  "Location": "Chicago, IL",
  "MessageType": "DISRUPTION_EVENT",
  "ReferenceNumbers": [],
  "Scac": "MTL",
  "Severity": "critical",
  "Shipper": "test-shipper",
  "Status": "Expired",
  "TagText": "Disruption: Test Flood Warning - IL",
  "Tags": [
    "Disruption: Test Flood Warning - IL"
  ],
  "Timestamp": "2026-07-14T07:08:05Z"
}

Field Descriptions

Event Metadata

Field Name	Description	Key Always Present?	Value Always Present?	Data Type	Max Length
MessageType	Identifies the callback family. Always "DISRUPTION_EVENT" for this callback type.	Yes	Yes	String	50
EventType	The specific disruption event type. Currently emitted as "disruption.shipment.created" for all weather disruption events (Phase 1). Additional event types (e.g. update, resolved) are expected as this callback matures.	Yes	Yes	String	100
DetectedAt	UTC timestamp (ISO 8601, "Z" suffix) indicating when FourKites' weather pipeline detected the disruption.	Yes	Yes	String (ISO 8601)	30
Timestamp	UTC timestamp (ISO 8601, "Z" suffix) indicating when this callback was emitted. In Phase 1 this matches DetectedAt.	Yes	Yes	String (ISO 8601)	30

Load Details

Field Name	Description	Key Always Present?	Value Always Present?	Data Type	Max Length
FourKitesLoadId	The internal FourKites load identifier for the shipment affected by the disruption.	Yes	Yes	Integer	N/A
LoadNumber	The customer-facing load/reference number for the affected shipment.	Yes	Yes	String	100
Shipper	The name of the shipper associated with the load.	Yes	No	String	255
Scac	The Standard Carrier Alpha Code (SCAC) of the carrier moving the load.	Yes	No	String	10
Status	The current status of the load at the time the callback was emitted (e.g. "In Transit", "Expired").	Yes	Yes	String	50
ReferenceNumbers	Array of additional customer reference numbers associated with the load. Emitted as an empty array when none exist.	Yes	No	Array of String	N/A
Tags	Array of tag strings applied to the shipment for this disruption (e.g. "Disruption: Test Flood Warning - IL").	Yes	No	Array of String	N/A
TagText	A single string containing the disruption tag text, mirroring the primary entry in Tags.	Yes	Yes	String	255

Disruption Details

Field Name	Description	Key Always Present?	Value Always Present?	Data Type	Max Length
DisruptionType	The category of disruption. Currently only "weather" is supported (Phase 1); OTR, Rail, Ocean, and Air values are planned for Phase 2.	Yes	Yes	String	50
EventCategory	The specific alert category as classified by the weather pipeline (e.g. "Flood Warning", "Tornado Warning").	Yes	Yes	String	100
AlertName	The human-readable name of the underlying weather alert.	Yes	Yes	String	150
Severity	The severity of the disruption. For weather, derived from NOAA priority codes and limited to "critical" or "general". Non-weather disruption types do not yet have a severity classification and will emit null until Phase 2 defines one.	Yes	No	String	20

Location

Field Name	Description	Key Always Present?	Value Always Present?	Data Type	Max Length
Location	The city and state of the disruption, formatted as "City, State" (e.g. "Chicago, IL"). Resolved via FourKites' per-load geographic matching. Non-weather disruption types currently only have event-level location without state/region.	Yes	No	String	255

Disruption Time Window

Field Name	Description	Key Always Present?	Value Always Present?	Data Type	Max Length
DisruptionStartedAt	Timestamp (ISO 8601 with UTC offset) marking when the disruption began.	Yes	Yes	String (ISO 8601)	30
DisruptionEndedAt	Timestamp (ISO 8601 with UTC offset) marking when the disruption ended. Reflects an "Expired" alert; may not be present for disruptions that are still active.	Yes	No	String (ISO 8601)	30

Disruption Scope

Field Name	Description	Key Always Present?	Value Always Present?	Data Type	Max Length
DisruptionModes	Array of transport modes affected by the disruption (e.g. "Ocean", "Rail", "TL"). For weather disruptions, always emitted as an empty array since weather impact is geographic rather than mode-specific. Phase 2 will populate this for non-weather disruption types.	Yes	No	Array of String	N/A

Usage Notes

DisruptionModes is always emitted as [] for weather disruptions, since weather impact is geographic rather than mode-specific.

Severity is currently limited to "critical" and "general" for weather alerts (mapped from NOAA priority codes). Other disruption types will emit null for Severity until a classification is defined.

Fields without an available value are emitted as null or an empty array/string rather than omitted; the callback is never dropped for partial data.

DisruptionEndedAt reflects a resolved/expired disruption and may be absent while the disruption is still active.