Tracking + On-Time Delivery

How it works

1. 1 Connect carriers. UPS and FedEx push tracking events via webhook in real time (one subscription per carrier account, configured from the Connections page with a signing secret you control). DHL + regional couriers land via poll workers on a 30-minute cadence.
2. 2 Events stream in. Each carrier event is HMAC-verified, idempotency-deduped, parsed into a normalized status, and matched to the corresponding invoice line item — all before the webhook returns a 200.
3. 3 OTD scores automatically. On the delivery event, the platform looks up the applicable SLA (effective-date scoped), computes the commit time using business-day arithmetic + your carrier's commit-time-of-day, and writes an on-time / late verdict against it.
4. 4 Claim-eligible findings fire. If a shipment is late on a guaranteed service, a pending-review audit finding shows up in the Parcel Audit claim queue with the carrier's filing URL, the commit timestamp, and the exact minutes-late — ready to submit.

Tracking map

• ✓MapLibre GL JS map with status-colored markers
• ✓Dashed polyline breadcrumb for each selected shipment
• ✓Filterable shipment list with prefix search
• ✓Four-chip status filter (in-transit / out-for-delivery / delivered / exception)
• ✓Event timeline side panel with carrier-native event codes
• ✓OTD verdict badge per shipment (on-time / late / claim-eligible)
• ✓Geofence overlay from existing telematics data (Fleet module)
• ✓Configurable tile host (MapLibre demotiles / Maptiler / self-hosted Protomaps)

On-Time Delivery dashboard

• ✓Total delivered, on-time %, late count, guaranteed breaches, avg minutes late KPIs
• ✓Daily trend chart (on-time % line + delivered volume bars)
• ✓Window toggle: 7 / 30 / 90 / 180 / 365 days
• ✓Per-carrier scorecard with color-coded on-time %
• ✓Claim-eligible feed linking into Parcel Audit findings
• ✓SLA-aware — late only if there's an actual commit to compare against

SLA configuration

• ✓Per-carrier, per-service SLA windows
• ✓Commit-days + commit-time-of-day in local carrier time
• ✓Business-day arithmetic with weekend + holiday exclusions
• ✓Effective-date versioning preserves historical verdicts
• ✓Guaranteed-service flag drives auto-claim creation
• ✓ON CONFLICT upsert keeps IDs stable across edits

Security + reliability

• ✓HMAC-SHA256 signature verification on every webhook — UPS signs the raw body; FedEx signs {timestamp}.{body} with a ±5 min skew window.
• ✓Per-connection unsubscribable URLs. Each carrier connection has its own URL with a UUID path segment; rotating a connection issues a fresh URL without affecting other connections.
• ✓Idempotent event handling. Carrier retries of the same event are 200 no-ops, never duplicate rows.
• ✓Append-only event log. shipment_tracking_events is trigger-protected against UPDATE and DELETE — audit history is immutable.
• ✓Multi-tenant scoped. Every query filters on organization_id; no carrier URL can post data into the wrong org.