Guides
What a Useful Webhook Payload Should Include
A developer-focused guide to shipment tracking webhooks, event design, retries, signatures, status changes, and payload structure.
A webhook is only useful if the receiving application can trust it, process it safely, and understand why it was sent. For shipment tracking, that means a webhook payload needs more than a tracking number and a status string.
A good payload should identify the event, show what changed, include the current normalized status, preserve carrier details, and give developers enough context to debug duplicate events, retries, and delayed carrier updates.
Every webhook needs stable identity
Webhook receivers should be able to detect duplicates. Network retries happen. Customer endpoints time out. A provider may resend an event after a temporary failure. Without a stable event ID, the receiving app may process the same delivery update multiple times.
A useful payload should include event_id, event_type, created_at, request_id, and tracking_number. If the customer has an internal shipment ID or order ID attached to the tracking record, that should be included too. Identity makes the event safe to store and replay.
Use event types that describe the reason for delivery
A generic webhook called tracking.updated can work, but more specific event types help customers build clearer workflows. Common examples include tracking.created, tracking.updated, tracking.in_transit, tracking.out_for_delivery, tracking.delivered, tracking.exception, and tracking.returned.
The event type should not replace the full payload. It should be a quick routing signal. The body should still include the full current tracking state so customers do not need to make a follow-up API call for basic information.
Include normalized status and raw carrier events
Normalized status is what most products need for UI and automation. Raw carrier events are what developers need for support and debugging. A strong webhook payload includes both.
For example, the payload can include status: delivered, carrier_code: royal-mail, carrier_name: Royal Mail, last_event: Delivered, and events: an array of timestamped carrier scans. This lets a customer trigger a delivered email while still showing the exact carrier wording in a detail view.
Make retries predictable
Webhook delivery should expect failure. Customer endpoints go down, deploys interrupt requests, and firewalls block traffic. A production webhook system should retry failed deliveries with backoff and expose the attempt count.
The payload or delivery metadata should show attempt number, previous failure reason when available, and the next retry time in the dashboard. This makes missed events visible instead of silently lost.
Sign every webhook
A webhook endpoint is a public URL. Without signatures, anyone who knows the endpoint can send fake events. A serious tracking platform should sign the payload with a per-endpoint secret and include a timestamped signature header.
The receiving app should verify the signature before processing the event. This protects order status, customer notifications, and downstream automation from forged requests.
Document the payload with real examples
Webhook documentation should include complete JSON examples for common events. Developers need to see delivered, exception, and in-transit examples before integrating. Partial snippets are not enough.
The best documentation also explains idempotency, retry timing, signature verification, status meanings, and how to test an endpoint from the dashboard. A webhook is not just a feature. It is a contract between systems.
Trace webhook direction
Trace is moving toward a webhook model where developers can configure endpoints in the dashboard, choose events, test delivery, and inspect recent attempts. The payload should stay compact, but it must carry enough context for production systems.
The goal is simple: when a parcel changes, your application should know what changed, why it matters, and how to handle the event safely.
Build tracking into your product
Create a Trace account, generate an API key, and test package tracking from the dashboard.