The DHL eCommerce Americas Tracking Webhook Management API allows clients to register webhook endpoints for specific pickup customer accounts and/or tracking ids, and receive real-time shipping events sent to their configured callback endpoints.

Scope

The following operations are allowed in the Tracking Webhook Management API:

Webhook Subscriptions

Tracking Webhook callbacks will contain information about a single package and include the complete track event history of that package, using the same payload format used by the traditional Tracking API responses.

To successfully consume webhook callbacks, 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.

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.

There are two types of webhook subscriptions -

• Pickup Account hooks
• Tracking ID hooks

Pickup Account hooks

This creates a hook at the pickup account level, and all packages that are created under that pickup account are eligible for the hooks. Clients may only create one webhook registration per pickup account. This subscription is permanent, and they will continue to generate and deliver hooks for all packages under the pickup account until the subscription is deleted.

Tracking ID hooks

This creates a hook for a specific package (trackingId) only. For trackingId based webhook subscriptions, we highly encourage clients to provide a pickup value also when creating the hook to guarantee that the hook is created for the correct package. We also recommend that clients perform a compare and match of the hook payload against the package metadata such as consignee city, state and country fields before consuming the events in the hook. This will ensure that you are not accidentally applying events from a hook to the incorrect package. This subscription is ephemeral and it will be deleted 7 days after a Delivered event has been sent or 60 days after the hook has been created (whichever comes first).

For both types of webhook subscriptions, before the webhook is created, the webhook URL will be checked for validity by sending a HTTP GET request; the server must reply with a HTTP 200 response in order to indicate that the endpoint is valid and active. For each webhook created, the response will contain a unique hookId identifying the webhook registration.

Request Description

M - Mandatory O - Optional C - Conditional N - Not Applicable

Response Description

M - Mandatory O - Optional C - Conditional N - Not Applicable

Body raw (json)

{
   "pickup": "5351244",
   "hookType": "TRACK_EVENTS",
   "url": "https://webhooktest.free.beeceptor.com",
   "username": "abc123",
   "password": "password",
   "active": true
}

This endpoint allows you to retrieve a list of all webhooks owned by the current API credentials.

Response Description

M - Mandatory O - Optional C - Conditional N - Not Applicable

Response Description

M - Mandatory O - Optional C - Conditional N - Not Applicable

Request Description

M - Mandatory O - Optional C - Conditional N - Not Applicable

Body raw (json)

{   "pickup": "5351244",
    "hookType": "TRACK_EVENTS",
    "url": "https://webhooktest.free.beeceptor.com",
    "username": "abc321",
    "password": "password",
    "active": true
}

Response Description

M - Mandatory O - Optional C - Conditional N - Not Applicable

Body raw (json)

{
     "pickup": "5351244",
     "hookType": "TRACK_EVENTS",
     "url": "https://webhooktest.free.beeceptor.com",
     "username": "abc321",
     "password": "password",
     "active": true
}

Response Description

A response code of 200 indicates the DELETE request has been completed successfully.