You can create tracking webhooks with ShipEngine to be notified of tracking updates while a package is being shipped to its destination.
Connect Your Carrier Account First
A carrier account needs to be connected to your ShipEngine account for automatic tracking updates to work correctly.
For example, if you would like to track FedEx packages, you will need to have a FedEx account connected to ShipEngine.
Webhooks can be created in your ShipEngine dashboard or via the API. Learn more about creating a tracking webhook via the API.
To set up a tracking webhook in the dashboard:
-
Go to the Developer section and select Webhooks.
-
Click the Add New Webhook button.
-
Select Api Track as the Webhook Event.
-
Enter the URL that you want webhooks to be delivered to in the Webhook URL field.
-
Click the green checkmark
to save your webhook.
You now have an active tracking webhook! You can create additional webhooks for updates on processing batches, connecting carriers, refreshing order sources, getting rates, and importing orders.
There are currently seven different status codes that may be returned in tracking responses. Those status codes are as follows:
|
Status Code |
Meaning |
|---|---|
|
AC |
Accepted |
|
IT |
In Transit |
|
DE |
Delivered |
|
EX |
Exception |
|
UN |
Unknown |
|
AT |
Delivery Attempt |
|
NY |
Not Yet In System |
Tracking payloads may vary depending on the carrier that is shipping the package. The webhook payload will include an array of all tracking events that have occurred for the package beginning with the most recent event. Below are example tracking payloads for popular carriers in raw JSON:
Stamps.com
{ "resource_url": "https://api.shipengine.com/v1/tracking?carrier_code=usps&tracking_number=9400111205476899201487",
"resource_type": "API_TRACK",
"data": {
"label_url": null,
"tracking_number": "9400111205476899201487",
"status_code": "AC",
"status_description": "Accepted",
"carrier_status_code": "GX",
"carrier_status_description": "A shipping label has been prepared for your item at 4:57 am on June 17, 2020 in SEATTLE, WA 98107. This does not indicate receipt by the USPS or the actual mailing date.",
"ship_date": null,
"estimated_delivery_date": null,
"actual_delivery_date": null,
"exception_description": null,
"events": [
{
"occurred_at": "2020-06-17T11:57:00Z",
"carrier_occurred_at": "2020-06-17T04:57:00",
"description": "Shipping Label Created, USPS Awaiting Item",
"city_locality": "SEATTLE",
"state_province": "WA",
"postal_code": "98107",
"country_code": "",
"company_name": "",
"signer": "",
"event_code": "GX",
"latitude": 47.3978,
"longitude": -122.3117
}
]
}
}
FedEx
{ "resource_url": "https://api.shipengine.com/v1/tracking?carrier_code=fedex&tracking_number=394084435504",
"resource_type": "API_TRACK",
"data": {
"label_url": "https://api.shipengine.com/v1/labels/se-12130064",
"tracking_number": "394084435504",
"status_code": "AC",
"status_description": "Accepted",
"carrier_status_code": "OC",
"carrier_status_description": "Shipment information sent to FedEx",
"ship_date": null,
"estimated_delivery_date": "2020-06-24T14:30:00-07:00",
"actual_delivery_date": null,
"exception_description": null,
"events": [
{
"occurred_at": "2020-06-22T06:47:23Z",
"carrier_occurred_at": "2020-06-22T06:47:23-07:00",
"description": "Shipment information sent to FedEx",
"city_locality": null,
"state_province": null,
"postal_code": null,
"country_code": null,
"company_name": null,
"signer": null,
"event_code": "OC",
"latitude": null,
"longitude": null
}
]
}
}
UPS
{ "resource_url": "https://api.shipengine.com/v1/tracking?carrier_code=ups&tracking_number=1ZR449430399243149",
"resource_type": "API_TRACK",
"data": {
"label_url": null,
"tracking_number": "1ZR449430399243149",
"status_code": "AC",
"status_description": "Accepted",
"carrier_status_code": "M",
"carrier_status_description": "Order Processed: Ready for UPS",
"ship_date": null,
"estimated_delivery_date": "2020-06-18T00:00:00",
"actual_delivery_date": null,
"exception_description": null,
"events": [
{
"occurred_at": "2020-06-16T21:52:15Z",
"carrier_occurred_at": "2020-06-16T21:52:15",
"description": "Order Processed: Ready for UPS",
"city_locality": "",
"state_province": "",
"postal_code": "",
"country_code": "US",
"company_name": null,
"signer": "",
"event_code": "M",
"latitude": null,
"longitude": null
}
]
}
}
DHL Express
{ "resource_url": "https://api.shipengine.com/v1/tracking?carrier_code=dhl_express&tracking_number=4013387803",
"resource_type": "API_TRACK",
"data": {
"label_url": null,
"tracking_number": "4013387803",
"status_code": "DE",
"status_description": "Delivered",
"carrier_status_code": "success",
"carrier_status_description": null,
"ship_date": "2020-06-16T05:27:00",
"estimated_delivery_date": "2020-06-22T15:00:00",
"actual_delivery_date": null,
"exception_description": null,
events": [
{
"occurred_at": "2020-06-16T16:34:14Z",
"carrier_occurred_at": "2020-06-16T16:34:14",
"description": "Customs status updated",
"city_locality": "CINCINNATI HUB,OH-USA",
"state_province": null,
"postal_code": null,
"country_code": null,
"company_name": null,
"signer": "",
"event_code": "RR",
"latitude": null,
"longitude": null
}
]
}
}
ShipEngine can track labels created outside of our API as long as we have an integration with the carrier. To set up automatic tracking updates for labels created outside of ShipEngine, you must start tracking updates at the Start Tracking endpoint.
It is possible to successfully create a tracking webhook in the ShipEngine sandbox environment. However, the sandbox does not create real labels that will be shipped, which means there will be no events for the webhook.
To stop tracking updates for a specific tracking number, use the Stop Tracking Updates endpoint.
To completely remove a tracking webhook from your account, you can use your ShipEngine account dashboard or the Delete Webhook endpoint.
To remove a webhook from the dashboard:
