Quick Answer
Use webhooks for primary shipment status updates, with polling reserved for reconciliation and recovery. Push delivery reduces stale dashboards and request volume, while scheduled polling catches missed carrier events, repairs failed deliveries, and confirms terminal states.
Introduction
A reliable shipment tracking API treats carrier scans as imperfect external facts, not commands that can overwrite your internal record without validation. A shipment-tracking webhook architecture works when events are authenticated, persisted, deduplicated, and applied through a controlled state machine. Carrier terminals produce scans at different times, with different vocabularies and occasionally delayed transmission. Your system must preserve what happened without allowing a late scan to create a fictional journey.
Key Takeaways
Webhooks should deliver operational updates, while polling verifies completeness.
Event IDs, timestamps, and idempotency protect tracking records from duplicate delivery.
State machines prevent delayed scans from creating impossible shipment transitions.
Where Shipment Status Updates Actually Originate
Shipment status updates begin with carrier scan events at terminals, depots, transfer points, and delivery stops. A barcode scan may represent physical receipt, loading, departure, arrival, attempted delivery, or a reported exception, but the carrier controls when that scan is emitted and when it becomes available to an integration layer. Normalize the carrier message, retain the original payload, and avoid treating missing scans as proof that a shipment did not move.
Normalize carrier language before publishing it
Use a small canonical vocabulary for customer-facing and operational workflows, then retain the carrier-specific code as metadata for investigation. This keeps notification logic stable even when individual carriers use different descriptions for the same operational stage. Shippers who want this normalization handled for them, rather than built in-house, can use Truxweb's LTL marketplace, which gives shippers one consistent view of quotes, bookings, and status across multiple LTL carriers instead of juggling each carrier's own systems and terminology.[1]
Booked: Shipment creation is confirmed.
Dispatched: Carrier accepted the movement request.
Picked up: Freight entered carrier custody.
In transit: Shipment moved between facilities.
Delivered: Final delivery was recorded.
Keep the carrier record alongside the canonical status
A canonical status is useful only if engineers can trace it to its source. Store the carrier name, external tracking identifier, raw status code, human-readable message, location when supplied, and raw payload reference. A disciplined shipping and logistics API layer separates inbound provider variation from internal order, support, and notification systems.
Webhook Architecture Shipment Tracking: Push vs Polling
Push vs polling is not a binary production decision. Webhooks should provide the live path, while polling provides a reconciliation path for carriers that do not publish events consistently, endpoints that were unavailable, and shipments stuck in a nonterminal state.
Compare the delivery models by operational failure mode
Polling asks for status whether anything changed or not; webhooks send an event after a change is available. For example, a platform tracking 10,000 active trips and polling every 5 minutes generates more than 2.8 million HTTP requests daily, according to webhooks versus polling analysis.[2] That request pattern is often wasteful when most tracked shipments are unchanged.
Criterion | Webhooks | Polling | Recommended control |
|---|---|---|---|
Update timing | Event-driven after publication | Limited by schedule | Use push for dashboard changes |
Request load | Changes generate deliveries | Every tracked shipment is queried | Use polling selectively |
Primary failure | Missed or rejected delivery | Stale result between checks | Persist and reconcile |
Recovery | Retries and replay | Next scheduled fetch | Run terminal-state checks |
The practical choice is a hybrid: process webhooks immediately, then run a reconciliation job for active shipments and unresolved exceptions. Devvpro's discussion of shipment webhook architecture is useful context when deciding whether that integration layer belongs in-house.
Define an event contract that survives provider changes
Every event should include an immutable event ID, shipment ID, canonical status, occurred-at timestamp, received-at timestamp, provider name, and schema version. A thin payload contains those fields plus a resource URL or reference, while a full payload includes the shipment snapshot; thin events reduce transfer size, but full payloads make replay and incident investigation easier when external state changes later.
A plain-text contract can remain compact: event_id, shipment_id, status, occurred_at, carrier_code, sequence, and payload_version. The shipping software architecture should keep this contract independent from any carrier's status vocabulary. This separation also supports freight API integration when multiple providers must map into one internal event contract.
Build Delivery Safety Into the Ingestion Path
At-least-once delivery idempotency is the safe assumption for shipment webhooks. Duplicate events happen after network timeouts, publisher retries, and consumer failures, so the handler must make the same delivery safe to process more than once.
Persist first, acknowledge quickly, process asynchronously
Verify the request, write the event and its idempotency key durably, then return a quick 2XX response before triggering slower downstream work. Use a uniqueness constraint on provider plus event ID, or on a deterministic key derived from the carrier event, so a redelivery becomes a no-op rather than a duplicate customer notification. Publishers can retry failed deliveries with exponential backoff schedules, so endpoints must tolerate repeated events over an extended retry window.[3]
Persist queue state changes, apply retry backoff and dead-letter queue controls, and retain failed events with their error context. Delivery acknowledgement should follow durable event persistence; process downstream business work asynchronously.
Authenticate the raw request, not a reconstructed payload
Webhook handlers should calculate HMAC-SHA256 over the untouched raw body, then compare the received and expected signatures in constant time. Check a signed timestamp to limit replay exposure, keep a distinct secret for each endpoint, and support overlapping secrets during rotation. OWASP's webhook security guidance recommends a distinct secret for each registered endpoint, limiting the impact of a leaked secret to one integration.
Apply Events Through a Controlled Shipment State Machine
A state machine prevents an old event from rewriting a newer reality. Do not sort solely by arrival time: record both occurred-at and received-at, prefer a carrier sequence number when available, and treat equal timestamps as a case requiring deterministic tie-breaking.
Reject transitions that contradict the shipment lifecycle
Allow booked to progress to dispatched, picked up, in transit, delivered, or exception, but reject a delayed dispatched event after a recorded delivery unless the provider explicitly marks it as a correction. Exceptions should be modeled as an overlay or a dedicated transition with a reason, not as a vague replacement for every current status.
Log rejected transitions as operational signals rather than silently dropping them. A strong freight platform architecture keeps an append-only event history, a derived current state, and a replay path that can rebuild state after code changes.
Observe the gap between carrier reality and your dashboard
Track delivery attempts, signature failures, duplicate suppression, queue age, state-transition rejects, and reconciliation mismatches. Alert on sustained failures rather than a single transient error, and give operators a replay tool that can reprocess one stored event or rebuild one shipment timeline without changing the original record. Subscribe only to event types the system handles to reduce unnecessary load and data retention, consistent with general webhook security practice.
Conclusion
Build shipment tracking around webhooks, not periodic polling, when timely operational updates matter. Make every inbound delivery idempotent, signature-verified, persisted before acknowledgement, and subject to explicit state-transition rules. Use polling only as reconciliation for active and exceptional shipments, where it can detect gaps without becoming the primary source of load. For teams designing the integration layer themselves, durable operational systems require careful handling of carrier events.
For practical architecture decisions, explore Devvpro's engineering guides.
Frequently Asked Questions (FAQs)
What is the difference between push and polling for shipment updates?
Push sends an event after a carrier publishes a status change, while polling repeatedly requests shipment state on a schedule, making push faster for live updates and polling useful for reconciliation.
How do you design a webhook for shipment tracking?
Webhook design for shipment tracking starts with an immutable event ID, shipment identifier, canonical status, occurred-at timestamp, provider metadata, signature, and a versioned schema that supports replay.
Why do shipment events arrive out of order?
Shipment events arrive out of order because carrier systems can publish scans late, delivery networks can delay requests, and retry behavior can redeliver an earlier event after a later one was processed.
How do you secure a webhook with HMAC signatures?
HMAC signatures secure a webhook when the receiver signs the raw request body with the shared secret, uses a constant-time comparison, validates a timestamp, and rotates endpoint secrets safely.
What is an idempotency key in webhook delivery?
An idempotency key in webhook delivery is a stable unique value, commonly the provider event ID, that lets the consumer recognize a redelivery and avoid repeating the state change or notification.
How does webhook retry with backoff work?
Webhook retry with backoff works by retrying a failed delivery after progressively longer delays, ideally with jitter, while failed business processing is retained separately for controlled replay from a dead letter queue.
Sources
- LTL Freight Marketplace vs. Broker: What Shippers Need to Know — Truxweb ↩
- Webhooks vs Polling for Logistics Tracking APIs — Intugine ↩
- Webhook Security — cheatsheetseries.owasp.org ↩
