Tracking Webhooks

Create tracking webhooks with ShipEngine to be notified of tracking updates while a package is being shipped to its destination. 

NOTE: A carrier account needs to be connected to your ShipEngine account in order 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.

This article includes:

Create a Tracking Webhook

Webhooks can be created in the dashboard or via the API. To set up webhooks in the dashboard, follow the steps below: 

  1. Go to the API Management section.
    API_mgmt.png

  2. Select the Webhooks tab and click Edit.
    webhooks.png

  3. Paste the URL that you want webhooks to be delivered to and toggle the Status bar.
    webhook_URL.png

  4. Click Save.

You now have an active tracking webhook!

Tracking Webhook Responses

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

 

Webhook Payloads

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

            }

        ]

    }

}

Labels Created Outside of ShipEngine

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

Sandbox Tracking Webhooks

It is possible to successfully create a tracking webhook in the sandbox environment. However, the sandbox does not create real labels that will be shipped, which means there will be no events for the webhook. 

Unsubscribe from Webhooks

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 the dashboard or the delete webhook endpoint.

If using the dashboard to remove a webhook:

  1. Go to the API Management section of the dashboard.
    API_mgmt.png
  2. Select the Webhooks tab and click Edit.
    edit_webhook_del.png
  3. Click the red X under the Delete column.
    del_webhook.png
  4. Save your changes.