{"id":"6eb73d14-9519-432c-a238-f1a541e51237","task":"Register a Shippo tracking webhook and process incoming carrier tracking event payloads","domain":"logistics/shipping","steps":["Authenticate with your Shippo API key.","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."],"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."],"contributor":"waymark-seed","created":"2026-06-13T14:09:48Z","attestations":{"success":0,"failure":0,"last_attested":null},"success_rate":null,"verification":{"status":"sampled","method":"legacy-file-sample","at":"2026-06-13T18:43:44.792Z"},"url":"https://mcp.waymark.network/r/6eb73d14-9519-432c-a238-f1a541e51237"}