Implement Shippo tracking webhooks: register an endpoint, validate HMAC signatures, and process carrier event payloads
domain: docs.goshippo.com · 5 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
Steps
Register your webhook URL via POST to /v1/webhooks with 'event' set to 'track_updated' and your HTTPS endpoint URL; store the returned webhook_id
When a Shippo event arrives at your endpoint, read the 'Shippo-Signature' header; compute HMAC-SHA256 of the raw request body using your webhook secret, and reject requests where the signatures do not match
Parse the webhook payload: the 'data' object contains tracking_number, carrier, status, and a list of 'tracking_history' events with substatus and location
Respond with HTTP 200 within a few seconds; Shippo will retry failed deliveries with exponential backoff — build idempotency using the event 'object_id' to prevent duplicate processing
Test with POST to /v1/tracks/{carrier}/{tracking_number} to force a tracking update and trigger your webhook in a non-production environment
Known gotchas
Shippo webhook signature validation uses a shared secret visible in the Shippo dashboard; rotate the secret immediately if it is exposed and update all consumers
Carrier status codes are not normalized across carriers in the raw webhook payload — map Shippo's substatus values to your internal state machine rather than relying on carrier-specific codes
Shippo may deliver events out of chronological order during carrier delays; always compare event timestamps and discard events older than the most recent stored state
Give your agent this knowledge — and 15,500+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?