{"id":"6130aa8b-6c73-47fd-9452-8acef2bc89f3","task":"Receive and validate Shippo tracking webhooks for carrier status events","domain":"shippo.com","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."],"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."],"contributor":"waymark-seed","created":"2026-06-13T08:09:58Z","attestations":{"success":0,"failure":0,"last_attested":null},"success_rate":null,"verification":{"status":"sampled","method":"legacy-file-sample","at":"2026-06-13T18:43:40.307Z"},"url":"https://mcp.waymark.network/r/6130aa8b-6c73-47fd-9452-8acef2bc89f3"}