Register a Shippo tracking webhook and process incoming carrier tracking event payloads

Steps

1. Authenticate with your Shippo API key.
2. 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'.
3. 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.
4. Validate the webhook payload authenticity using the signature header Shippo sends (verify header name and signing algorithm in current docs) against your webhook secret.
5. Map 'tracking_status.status' values (e.g., 'TRANSIT', 'DELIVERED', 'RETURNED', 'FAILURE', 'UNKNOWN') to your internal delivery state machine and update order records accordingly.
6. 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.