6 Track and Trace Pusher

6.1 Intro

The Track & Trace Pusher is a component that enables push-based updates for every update to a parcel.

There are two ways to receive updates:

  1. The pusher is subscription based per parcel, meaning that for every parcel you wish to receive updates from, you’ll need to subscribe.
  2. Organisation based pushing, where all parcels linked to your organisation’s account numbers will automatically be pushed to your API without requiring individual subscriptions. Once enabled, you no longer need to subscribe to individual parcels.

In order for the pusher integration to work, configuration needs to be set up. This includes, for example, the URL you wish to receive updates on, or the API key that is required for your services.

High level overview

In order for your systems to receive updates for a parcel, the following steps need to happen:

  1. Your Engineer will manage configurations from a UI. We call this the Configuration phase, and it should happen only for initial setup or when your APIs change. A more detailed description can be found in the section Managing configurations.
  2. When a configuration is created, you are given a configurationId and subscriptionKey. Together with the parcel’s barcode and postalCode, your systems will be able to subscribe to a parcel. However, subscribing is not mandatory. Alternatively, you can choose to enable Organisation Based Pushing. When this is enabled, all parcels linked to your organisation’s account numbers will automatically trigger push updates to your configured endpoint, without the need for individual subscriptions. See the section Subscribing for more details.
  3. Once subscribed to a parcel, or when Organisation Based Pushing is enabled, the URL that you configured in step 1 will be called for every update to that parcel. In the section Receiving updates, more details can be found.

6.2 Services

6.2.1 Managing configurations

To receive updates for parcels, one first needs to set up a configuration. This is done in the following way:

Login via https://my.dhlecommerce.nl with the business account that has the right role; at least one account is provided during onboarding. Then under ‘Settings > Integrations’ open up the ‘Track and Trace pusher’ integration.

Details

There are a few properties that we currently recognize:

  • name (mandatory): The name of this configuration.
  • url (mandatory): The URL you wish to receive updates on. Only the https scheme is allowed.
  • maxRequestsPerSecond (optional): The number of requests your API is capable of handling per second. Default value: 100 requests per second. Our systems will respect this value and throttle the number of calls we do to your API. See the Rate limiting section for more information on rate limiting.
  • webhookAuthentication (mandatory): See section Webhook authentication for more information.
  • enableOrganisationBasedPushing (optional): Default is false. When set to true, all parcels linked to your organisation’s account numbers will automatically be pushed to your API without requiring individual subscriptions. This is useful when you want to receive updates for all your shipments automatically. If you enable this option, you no longer need to create subscriptions for individual parcels.

Note that your account may contain multiple configurations. Every configuration comes with a unique configurationId and subscriptionKey pair; subscribing to parcel updates is done with these values. Treat your subscriptionKey as though it is a password - do not add it to your app code or public repositories and do not share it with anyone.

With the setup of multiple configurations it is possible to have parcel updates pushed to different URLs. Example scenarios where this can be useful:

  • A test configuration used for testing purposes.
  • Route parcel updates to both your test and prod environments.
  • Route parcel updates to different parts of your system.
  • Route different parcels to different URLs.

Note: there is a maximum of 50 configurations per account.

6.2.2 Subscribing

To subscribe to a parcel’s updates, you need to use the subscription endpoint with the configuration credentials and parcel information.

Note that the barcode does not need to be known yet in our systems. This allows you to subscribe to parcels ahead of time, before they are processed by DHL. However, because of this, we cannot verify at the time of subscription whether the subscription was successfully linked to a valid parcel. Confirmation only occurs once events start being pushed.

Each configuration that you created comes with a unique configurationId and subscriptionKey pair. Together with a parcel’s barcode and postalCode, these values can be used to subscribe.

Subscription is done with a POST on the subscription URL. The subscriptionKey should be provided in the Authorization header with the SubscriptionKey scheme. Example: Authorization: SubscriptionKey yourActualKey. The rest of the values is passed as JSON object in the request.

To help with debugging and verification, the Pusher configuration UI offers a “Last subscriptions” tab. There, you can view your last 100 parcel subscriptions.

6.2.3 Receiving updates

If all went well, our systems will call the URL you provided with every update to a parcel you subscribed to or when using Organisation Based Pushing. The ordering of updates is guaranteed per parcel. Calls are done one-by-one and in chronological order.

Each push contains the entire current state of the parcel, not just the latest event. This includes all events so far in the parcel’s journey, bundled in the events array. The most recent event (the one that triggered the push) is always the last item in the events list.

Please note that it is possible to receive identical parcel data multiple times, even when there are no visible changes in the Track & Trace model. This may happen when internal DHL events occur that don’t alter the public-facing parcel data.

The model that is pushed is equal to the model that is fetched from our /track-trace endpoint, with minor differences:

  1. We push only a single piece, while from the T&T API you can fetch multiple at once. Consequently, we push a JSON object containing the data; for the T&T API you retrieve an array.
  2. With the T&T API you are also given a view field in the response. We never push that view field.

Note: In Organisation Based Pushing, it is possible that you receive updates for barcodes that are not yet known to your systems. This is especially common with return parcels.

6.2.4 Rate limiting

The maxRequestsPerSecond property that you provided in the configuration phase is respected. We buffer requests if more updates come in than your API is capable of handling. No update is ever lost by this throttling.

We recommend setting your maxRequestsPerSecond to at least 100 for optimal performance. This ensures your system can handle peak volumes of parcel updates without excessive queuing. Your system should be designed to handle this rate of requests consistently.

Note: if you have multiple configurations pointing to the same URL, the maximum amount of traffic you can expect on this URL is the sum of maxRequestsPerSecond for these configurations.

6.2.5 Request handling

We distinguish between two types of push handling results, one that removes the item from the push queue and one that does not.

Important: You should never reject the request simply because your system cannot process it at that moment. Instead, you should always accept the request (respond with a 2xx), store the data locally, and process it asynchronously on your side. This ensures reliable delivery and avoids unnecessary retries or circuit breaker activation.

Removal from the queue

In case that your API is capable of handling the request, you should provide a 2xx response. In this case the push is removed from the queue and processing continues on the remainder of events.

In case your API is returning a 404 response code, we interpret that as you do not know the parcel. In this case we also remove the push from the queue and processing continues on the remainder of events. New updates to the same parcel will be tried again.

Request failure

In case that your API is not capable of handling the request, you should provide a non 2xx/404 response. In such event our retry mechanism/circuit breaker kicks in.

Retry Mechanism
  • The request is retried until it is either successful or no longer considered relevant: 3 days after inception of the event.
  • Retries are performed with exponential backoff to prevent overwhelming your system.
  • Each parcel update is managed independently, so one failing parcel doesn’t block updates for other parcels.

Failure of pushing an update for one parcel will never result in pushing being halted for other parcels. If too many requests of too many pieces result in error, a CircuitBreaker trips.

Circuit Breaker

To protect both our systems and yours, we implement a circuit breaker pattern:

  • If too many requests result in errors (failure rate exceeds 50% over a 10-second window), a CircuitBreaker is tripped.
  • When the circuit breaker opens, we temporarily stop trying to push most updates to your system.
  • In “Open” state, only a small number of test requests are sent periodically to check if your system has recovered.
  • Once these test requests are successful, the circuit breaker moves to “Half-Open” state, gradually allowing more traffic.
  • After consistent success, the circuit breaker returns to “Closed” state and normal operation resumes.
  • The circuit breaker operates independently for each configuration.

Important: The CircuitBreaker protects both our systems and your API from excessive load during extended failure periods. When a circuit breaker trips for a configuration, it temporarily affects all parcels being pushed for that configuration. Other configurations remain unaffected and continue normal operation.

Your system should be able to handle at least 100 requests per second under normal operation for optimal performance.

Once an event is considered to be no longer relevant, it will be removed from the queue and processing continues on the remainder of events.

6.2.6 Webhook authentication

We require you to setup authentication for your API. In this way you are sure that updates came from the DHL pusher, and not from any unauthorized party. Currently we support two authentication methods: API keys and OAuth2 Client Credentials Grant Flow.

Via an API key

During configuration setup you provide us with the following properties:

  • webhookApiKey (mandatory): An API key that we will provide in an HTTP header with every call we do to your system. The webhookApiKeyHeader property can be used to setup which header that should be. The API key should be between 50 and 150 characters long.
  • webhookApiKeyHeader (optional): The HTTP header that we will put the webhookApiKey in. Defaults to Authorization

Via OAuth2 Client Credentials Grant Flow

During configuration setup you provide us with the following properties:

  • clientId (mandatory)
  • clientSecret (mandatory)
  • authorizationServerUrl (mandatory)

At runtime, we will request an access token with a POST call to the authorizationServerUrl with the clientId and clientSecret as basic auth credentials. The access_token provided by your authorizationServerUrl we then use as Bearer token in the Authorization header.

The response from your authorizationServerUrl yields 200 with a json response:

{
  "access_token": "String",
  "token_type": "String",
  "expires_in": "Long",
  "scope": "String"
}

in case of successful authentication.

We cache the token for a time of expires_in seconds.

Failure to authenticate yields retrying as if pushing the parcel failed. See the Request failure paragraph above.

6.3 API Usage

Description URL
Base URL for subscription API https://pusher.dhlecommerce.nl/track-trace-pusher/subscriptions
Swagger documentation https://pusher.dhlecommerce.nl/docs

6.3.1 Subscribe to parcel updates

Request examples

Curl 
curl -X POST "https://pusher.dhlecommerce.nl/track-trace-pusher/subscriptions" \
  -H "Authorization: SubscriptionKey yourActualKey" \
  -H "Content-Type: application/json" \
  -d '{
    "configurationId": "your-configuration-id",
    "barcode": "parcel-barcode",
    "postalCode": "parcel-postal-code"
  }'

Responses

Success (code 204)

No content is returned for a successful subscription.

Bad Request (code 400)

Returned when request body is invalid.

6.4 Testing

Since the Track & Trace Pusher is a push-based service, testing requires setting up a webhook endpoint in your systems to receive the push notifications.

Suggested test approach:

  1. Set up a test configuration in the Track & Trace Pusher UI pointing to your test environment.
  2. Implement a webhook endpoint in your test environment that can receive and process push notifications.
  3. Subscribe to a real or test parcel using the subscription API.
  4. Verify that your webhook endpoint receives updates for the subscribed parcel.

Frequently Asked Questions

Is it possible to subscribe to multiple parcels with one call?
No, currently we do not provide such API.

Do you push the entire parcel with all events, or do you just push the latest event?
We push the entire parcel with all previous events for every update that we have. That is, the last entry in the events field is the event that triggered the push.

I’m getting a 401 while subscribing
Have you tried:

  • Are you using the production environment credentials and production environment configurationId and subscriptionKey? The production environment has the following base url: https://pusher.dhlecommerce.nl/
  • Does the Authorization header contain the right SubscriptionKey scheme (and not a Bearer for example)? Valid is: Authorization: SubscriptionKey yourActualKey

Do you guys have a test environment where we can validate our pusher integration
Unfortunately it’s quite hard to setup a proper test environment, as we would need to cycle test parcels in that environment and get them in the right status. We are currently investigating ways of doing this. You could always create a Test configuration in our production environment. That test configuration could point to your testing environment. We recognize that this setup is sub-optimal.

Our APIs are using IP allow lists, can you provide us with IP addresses from where you push?
The pusher is being hosted from the Azure Cloud in the West-Europe region. IPs can be found in the following document: https://www.microsoft.com/en-us/download/confirmation.aspx?id=56519. It is unclear how often these IP addresses change, or when they will. Hence, we cannot provide you with any notification when such event would be happening.

Are API keys in the MDP UI in any way related to the pusher?
No, these are unrelated.

What are the response codes for the subscription endpoint?
In principle you should always receive a 204 for a valid subscription. In case your body is invalid, you’ll receive a 400. This API is currently not rate limited.

What is the difference between url and authorizationServerUrl properties in a configuration?
The url is where we POST all data to, it should contain a reference to your API that is capable of handling parcel updates. The authorizationServerUrl is used only in the OAuth2 Client Credentials Grant Flow authorization scheme; it is your authorization API where we exchange credentials for a token.

Is it possible to filter events so that we only receive a subset? A filter by parcel status for example?
No, currently no such mechanism is in place.

How many requests should my system be able to handle?
Your system should be designed to handle at least 100 requests per second consistently. This is the recommended minimum capacity for systems receiving push updates, especially during peak shipping seasons when update volume increases. The Track & Trace Pusher is built to handle high volumes of events and will respect your configured maxRequestsPerSecond setting.