ShippingV2Service

Chokepoint disruption alert (outbound, signed)

WorldMonitor POSTs this event to the callbackUrl you register via RegisterWebhook when a subscribed chokepoint's disruption score is at or above your alertThreshold (and its live signals above minLiveSignal when set), once per crossing, including one already in progress at first evaluation. It re-arms below the threshold unless a score input missing since the last delivery could explain the drop. Failures retry every 5 minutes with the same X-WM-Delivery-Id while the score holds; 5 failed ticks deactivate the webhook. Full rules at https://www.worldmonitor.app/docs/api-shipping-v2#delivery-worker.

Verify X-WM-Signature-V2 in constant time against sha256= + hex(HMAC-SHA256(key=secret, message=timestamp.deliveryId.event.rawRequestBody)). Use the exact header strings and raw body bytes. Use secret verbatim; do not hex-decode it or re-serialize JSON. Reject missing or malformed headers and timestamps more than 300 seconds in the past or future. Require V2; never fall back to the legacy body-only signature. Atomically dedupe verified delivery ids for the subscription lifetime. Retries keep the id but refresh the timestamp and signature. Respond with any 2xx to acknowledge receipt.

postWebhookchokepoint.disruption

Headers

X-WM-Signaturestring required
Example:sha256=2b8c0d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c

Legacy body-only HMAC-SHA256. No replay protection. Migrate to V2.

X-WM-Signature-V2string required

HMAC-SHA256(secret, timestamp.deliveryId.event.rawRequestBody).

X-WM-Timestampstring required

Send time in Unix seconds. Accept within 300 seconds of the receiver clock.

X-WM-Event'chokepoint.disruption' required

Always chokepoint.disruption for this body. The other events (country.risk_surge, news.breaking, market.move, natural.hazard) send the same headers and signature with the payloads documented at https://www.worldmonitor.app/docs/api-shipping-v2#delivery-format.

X-WM-Delivery-Idstring required
Example:whd_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d

Unique delivery identifier (whd_ + 32 hex chars). Use it to dedupe retries and process deliveries idempotently.

Payload

subscriberIdstring required

The wh_-prefixed subscription receiving this alert.

chokepointIdstring required

Chokepoint that breached the threshold (e.g. suez).

scorenumber required

Current disruption score of the chokepoint, 0-100.

alertThresholdnumber required

The subscription's configured alert threshold, 0-100.

triggeredAtstring date-time required

ISO-8601 timestamp when the alert fired.

reason'ais_congestion_spike' | 'navigational_warning' | 'transit_drop' | 'score_threshold' required

First matching rule in this order; score_threshold when none matches.

detailsobject

Name, status, warning and AIS counts, congestion, war-risk tier, transit change, previous score, feed time.

Response

Any 2xx acknowledges receipt. A non-2xx response or a delivery timeout marks the delivery failed.

Changes

Webhooks have no change history: a webhook is keyed by its event name rather than a path and method, so no recorded change can name it.