With proactive tracking notification, users of the DHL Shipment Tracking API can now receive push notifications on the status of their shipments, including delivery time and routing updates etc.

You can subscribe for updates in two ways

• based on TrackingID*
• based on Customer AccountID*

*see supported subscription scenarios

Advantages of Push Notifications

Push updates provide close to real time status updates ad continuously keeps consumers up-to-date. No need for actively requesting the latest shipment update in order to have the latest status. 

Improved Customer Experience

Push updates provide a versatile and straightforward solution, easily integrated into the customer's workflow with minimal setup required. The result is real-time notifications delivered at reduced costs.

Supported Products

• eCommerce
  • Europe:  Cross-border products (Parcel Connect, Return Connect, Parcel International, Connect PLUS, Return International) 
  • Parcel UK: Parcel Connect, Return Connect, Worldwide Air, Parcel International, International Road Economy  
  • Parcel NL, domestic shipments
  • PPL, domestic (CZ)  shipments
     
• P&P (Post und Paket)
  • Brief
    • Einschreiben National, Einschreiben, Einschreiben Rückschein, Einschreiben Eigenhändig, Einschreiben Einwurf, Wert, Prio, Nachname, Einschreiben International, Einschreiben Rückschein International, Einschreiben Eigenhändig International, Wert National, Warenpost Tracked International, Ländernachweis, Postzustellungsauftäge (PZA)
       
• Global Forwarding 
  • SameDay: SameDay Jetline Unaccompanied shipment, SameDay Jetline accompanied shipment, Same Day Speedline, SameDay Sprintline 
  • eCommerce shipments

Coming soon - not yet supported

• P&P, Paket, Post International (DPI), Internetmarke
• eCommerce - US,
• Global Forwarding, Airfreight, Ocean Freight
• Express

Notifications will have the same format as the traditional request & response UTAPI documented at: https://developer.dhl.com/api-reference/shipment-tracking

Retry mechanism

To ensure you do not loose any notifications in the case your system is not available this push API comes with a retry mechanism.

To successfully consume our notification, the receiving system must:

• use a valid SSL certificate and
• reply to the event POST request with a HTTP 200 response within 5 seconds.

If either of these requirements is not met, the system will retry delivery in 1 hour. If the second delivery fails, the system will retry delivery 6 hours after the second delivery attempt. If the third delivery fails, the system will not try to send the event again and the technical contact associated with the account will be notified of the deactivation via email. If event delivery fails 10,000 times consecutively for a specific webhook, that webhook will be automatically deactivated, and the technical contact associated with the corresponding pickup customer account will be notified of the deactivation via email.

Supported Subscription scenarios

Get Access

Access is free of charge for all customers. If you are a third party please contact our support team. 

You are required to request credentials for any and all applications you develop as described below.

To register your app and get your API subscription keys:

1. Click My Apps on the portal website.
2. Click the + Add App button.
   The “Add App” form appears.
3. Complete the Add App form. 
   You can select the APIs you want to access.
4. When you have completed the form, click the Add App button.

Authentication

Every call to the API requires a subscription key. This key needs to be passed through a request header (DHL-API-Key).

To view your API subscription keys:

1. From the My Apps screen, click on the name of your app.
   The Details screen appears. 
2. If you have access to more than one API, click the name of the relevant API. 
   Note: The APIs are listed under the “Credentials” section. 
3. Click the Show link below the asterisks that is hiding the Consumer Key. 
   The Consumer Key appears.

Environments

The addressable API base URL/URI environments are:  

Setup process

How to create and activate subscription please refer to the Reference Docs.

Two types of subscription are supported - 

• by Shipment (immediate activation)
• by Account,  (Business approval is required to fully activate account subscription)

1) Create subscription notification

Once a subscription has been created your webhook will receive a confirmation about the subscription creation. This confirmation will  contain a "secret"  in the header and the same value is also listed as a secret in the body. This "secret" is needed to confirm you are owner of the webhook and to active the subscription

Example:

{
  "self": "https://api-eu.dhl.com/tracking/push/v1/subscription/94d0131a-66b1-450d-82ac-4566b29c3dc1",
  "scope": "subscription.validate",
  "expires": "2022-11-08T15:27:09.021945677Z",
  "secret": "rZxQ2L1FDlbuaQObrAhtgq",
  "note": "Subscription validation token provided."
}

2) Activate subscription notification

Once the subscription has been activated the webhook will receive a confirmation about the subscription activation. Upon activation the subscription is ready to provide tracking updates.

Example:

{
  "self": "https://api-test.dhl.com/tracking/push/v1/subscription/94d0131a-66b1-450d-82ac-4566b29c3dc1",
  "scope": "subscription.ready",
  "expires": "2023-05-02T15:32:15.33751504Z",
  "note": "Subscription ready for notifications."
}

3) Receive Shipment notifications

The webhook will receive notifications about status and e.g. delivery time of a shipment. For shipments data schema, please refer to the "specification of a consumer web-hook endpoint" file in the download section

Example:

{
    "self": "https://api-eu.dhl.com/push/subscription/94d0131a-66b1-450d-82ac-4566b29c3dc1",
    "scope": "subscription.push",
    "expires": "2025-04-08T12:26:31.919Z",
    "note": "Event push message",
    "shipments": [
        {
            "id": "7777777770",
            "service": "ecommerce-europe",
            "status": {
                "timestamp": "2023-03-02T07:53:47Z",
                "location": {
                    "address": {
                        "countryCode": "NL",
                        "postalCode": "1043 AG",
                        "addressLocality": "Oderweg 2, AMSTERDAM"
                    }
                },
                "statusCode": "transit",
                "status": "in customs",
                "description": "The shipment is pending completion of customs inspection.",
                "pieceIds": [
                    "JD014600006281230701",
                    "JD014600006281230702",
                    "JD014600006281230703"
                ],
                "remark": "The shipment is pending completion of customs inspection.",
                "nextSteps": "The status will be updated following customs inspection."
            }
        }
    ]
}

specifics for the use of Tracking Data

• Tracking data is provided to You and/or the entity you are authorized to represent (hereinafter “You”/”Your”)  via this SHIPMENT TRACKING API under the prerequisite, that You retrieved the according tracking number in compliance with the applicable law, especially in the field of data protection and competition law and that You use the tracking number and/or tracking data solely for Your own legitimate tracking purposes.
• You may only submit tracking data to the recipient of DP DHL Group shipment and no other person; such submission shall always been in compliance with applicable laws in the field of data protection and competition law, which includes that the data shall not be combined with advertisement or presented in a way that it could be regarded as advertisement.
• If You are neither the sender nor the recipient of DP DHL Group-shipment/s, the tracking data refers to,
  • You shall ensure, that you are authorized to act on behalf of the sender
  • You shall make the sender aware of the restrictions set out in this User Guide just as the General Developer Portal Terms of Use
  • You shall make the sender aware of the necessity to inform the recipient transparently about the processing of his/her personal data according to applicable data protection laws.
• In no case shall you reveal and/or provide third parties with the tracking number and/or tracking data and/or analyze, modify such data in any form and/or derive data/information especially for competitive reasons from it without our prior written consent.
• Tracking data shall be used in accordance with the following specification:
  • Display “Delivered by Deutsche Post DHL Group“ in text (minimum font size) as soon as it is presented/submitted to recipient
• You shall delete the tracking number and tracking data which You received via the SHIPMENT TRACKING API 30 days after the delivery (of the shipment) to the recipient is completed.