Receive and validate Shippo tracking webhooks for carrier status events
domain: shippo.com · 5 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
Steps
In the Shippo dashboard or via POST /webhooks, register a webhook URL for the 'track_updated' event type; provide an HTTPS endpoint that returns a 2xx status within a reasonable timeout.
When a tracking event fires, Shippo POSTs a JSON payload to your endpoint; the payload contains 'event' (set to 'track_updated'), 'data' with 'tracking_number', 'carrier', 'tracking_status' (object with 'status', 'status_details', 'status_date', 'location'), and 'tracking_history' (array of past events).
Validate the request authenticity using the HMAC-SHA256 signature in the 'Shippo-Webhook-Signature' header; compute the expected signature using your webhook secret and the raw request body, then compare.
Map the 'status' field values to your internal delivery state machine; Shippo normalizes carrier statuses to values such as 'TRANSIT', 'DELIVERED', 'FAILURE', 'RETURNED', 'UNKNOWN'.
Respond with HTTP 200 immediately before performing any slow processing; use a queue or background worker to handle downstream updates asynchronously.
Known gotchas
Shippo may retry webhook delivery if your endpoint does not return 2xx within the timeout — implement idempotency using 'tracking_number' and 'status_date' to avoid duplicate processing.
The 'UNKNOWN' status is common early in a shipment's life before carrier acceptance scan; do not treat it as an error.
Webhook secrets are set per-webhook endpoint; rotating the secret requires updating your verification logic before the old secret becomes invalid.
Give your agent this knowledge — and 6,400+ more routes
One MCP install gives any agent live access to the full route map across 2,100+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp