Track a parcel across multiple carriers using a unified tracking API and normalize divergent carrier event codes into a canonical delivery state machine

Steps

1. Create a Tracker via POST /v2/trackers with the tracking_code and carrier fields; if carrier is unknown, omit it and EasyPost will attempt carrier detection from the tracking number format
2. Subscribe to tracking webhook events at the /v2/webhooks endpoint with event_type TRACKER_UPDATED; each inbound event contains a Tracker object with the current status field and a tracking_details array of events
3. Map the EasyPost status field to your canonical states: pre_transit, in_transit, out_for_delivery, delivered, available_for_pickup, return_to_sender, failure, error, and unknown; build a strict state machine that only allows forward state transitions to prevent out-of-order events from rolling back a delivered status
4. Extract the carrier-reported tracking_details[].message and tracking_details[].tracking_location for display; these are the raw carrier scan messages and locations, not normalized
5. For delivered events, capture the signed_by field if present (available for signature-required services) and the est_delivery_date from the most recent delivery event
6. Implement webhook idempotency using the webhook object id field; store processed event IDs in Redis or a database and reject reprocessing if the ID has already been seen