Best Practices: Webhook Design for Carrier Tracking
A guide rooted in experience
If you’re a carrier designing a tracking webhook, this guide summarizes best practices I’ve learned from operating integrations with 1,200+ carrier systems over the years, while maintaining data-compliance requirements.
Baseline approach: Push all events by shipper account
A common industry pattern is: emit all tracking events for all shipments associated with a given shipper account (e.g., an API key / customer account). This works for a narrow set of use cases, but it’s not sufficient for the broader market.
If shipper-account push is the only model you support, you force downstream consumers to build workarounds (or you block key partner integrations entirely).
Know your real consumers: Who actually needs tracking?
In modern shipping workflows, the shipper is often not the primary consumer of tracking events. The real demand comes from an ecosystem of third parties, including:
marketplaces and retail channels
payment providers
ticketing/support systems
analytics platforms
consolidators and 3PLs/fulfillment providers
customs brokers
insurance providers
other operational partners and internal tools
Requiring each shipper to individually integrate your carrier tracking into each partner system creates unnecessary friction and puts your customers at a disadvantage versus carriers that support partner-friendly subscription models.
Recommended: Subscription API for tracking-ID–scoped webhooks
Provide an API that allows authorized parties to subscribe to tracking updates for a specific Tracking ID (or shipment identifier). This enables ecosystem partners to receive events directly, without requiring the shipper to relay data.
Key properties of this model:
subscriptions are scoped (per Tracking ID / shipment)
subscriptions are authorized (who can subscribe is enforced)
events are push-based (webhook delivery)
Subscription responses: Validation and error handling
The subscription endpoint should return explicit, developer-friendly responses that make it unambiguous whether the subscription was created.
At minimum
:
confirmation that the subscription is active (or pending)
the scope (e.g., Tracking ID, carrier, account)
a unique subscription ID
clear error codes/messages when it fails (and why), such as:
invalid Tracking ID
unauthorized / insufficient permissions
invalid webhook URL or failed verification challenge
duplicate subscription
rate limit / quota exceeded
Mid-journey subscriptions: Handling historical events
A subscription may be created after a shipment has already started moving. In that case, partners typically need the full event history to establish state (current status, milestone timestamps, exceptions, etc.).
Two common approaches:
Option A (basic): Separate “get history” API
Provide a REST endpoint to fetch historical tracking events. The consumer must:
call the history API, then
start listening to the webhook, then
merge/dedupe events by event ID / timestamp.
Option B (best): Return history on subscription creation
When creating the subscription, return any existing historical events (if available) in the subscription response. This allows the consumer to become consistent immediately without implementing a two-step bootstrap flow.
Data Privacy Compliance
To understand more on how carriers can provide shipment tracking while staying compliant with data privacy frameworks such as GDPR, CCPA, and PDPA, check out this article on Why Carriers Need DPAs for Tracking Data.
