POST to the webhooks endpoint with 'url' (your HTTPS endpoint), 'event' set to the relevant event type (e.g., 'track_updated'; verify available event types in current docs), and 'active: true'.
In your webhook handler, parse the JSON body; the payload contains an 'event' field and a 'data' object with tracking details including 'tracking_number', 'carrier', 'tracking_status.status', 'tracking_status.location', and 'tracking_history' array.
Validate the webhook payload authenticity using the signature header Shippo sends (verify header name and signing algorithm in current docs) against your webhook secret.
Map 'tracking_status.status' values (e.g., 'TRANSIT', 'DELIVERED', 'RETURNED', 'FAILURE', 'UNKNOWN') to your internal delivery state machine and update order records accordingly.
Respond to the webhook with an HTTP 200 status promptly (within a few seconds); defer any heavy processing to an async queue to avoid Shippo retrying the delivery.
Known gotchas
Shippo may retry webhook deliveries if your endpoint returns a non-2xx response or times out; implement idempotent event handlers keyed on a unique event identifier to handle duplicate deliveries safely.
Tracking webhooks may arrive out of chronological order; compare 'tracking_status.status_date' timestamps before updating your system to avoid regressing a delivered status back to in_transit.
Not all carriers provide granular tracking events; for carriers with sparse scan data, 'tracking_history' may remain empty until final delivery.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp