DHL Push API Virtual Sandbox

Automated event notifications for DHL Global Forwarding shipments.

The DHL Push API enables real-time event-driven communication for Global Forwarding services. It allows developers to subscribe to specific shipment milestones, invoice updates, and timestamp notifications, ensuring systems remain synchronized with logistics events as they occur.

Use this hosted sandbox to simulate DHL Push API APIs without authentication, API keys, or extra dependencies. Point your code or SDK to the Beeceptor base URL, preferably through an environment variable or feature flag, and switch back to the production API when ready. This keeps your integration code consistent across local development, QA, demos, and production.

Use cases:

Use this sandbox to validate subscription registration, test webhook delivery payloads for invoice and timestamp events, verify subscriber-id filtering logic, and handle asynchronous notification retry scenarios without triggering live logistics workflows.

DHL Push API virtual sandbox is up and running!

Use this sandbox URL as the API base in your code to simulate DHL Push API responses instantly.

`https://dhl-push-api.mock.beeceptor.com`

Timestamp Push API v1

POST

/subscription/timestamp-notification

Use this operation to subscribe to timestamp notifications for the shipments you booked using the Shipment Booking API. For more information on Shipment Booking API see https://developer.dhl.com/api-reference/dgf-shipment-booking#get-started-section/overview

Request Payload

{
  "callback-url": "https://brisk-safe.net/",
  "enable": true,
  "http-headers": {
    "Authorization": "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==",
    "Content-Type": "application/json",
    "x-api-key": "p7fe80848edde",
    "x-sender": "DHL"
  },
  "support-email-address": "Rosa55@gmail.com"
}

Response Payload

{
  "api-correlation-id": "a3e031eb-84dc-4dbb-8312-527c7ff5f271",
  "detail": "Push Notification Updated(Enabled)",
  "status": 200,
  "title": "OK"
}

{
  "api-correlation-id": "6e772255-a1e4-4f87-97ea-e5986973d6c1",
  "detail": "Expired Access Token",
  "status": 401,
  "title": "Unauthorized"
}

{
  "api-correlation-id": "957b29db-9d00-43be-ac6a-ab4b70b5cea2",
  "detail": "Server failure",
  "status": 500,
  "title": "Internal Server Error"
}

Sales Invoice Push API

POST

/subscription/invoice

Use this operation to subscribe to Invoice data once shipment invoice is posted by DHL Global Forwarding. Developer can choose to receive a notification message or choose to receive the Sales Invoice data

Request Payload

{
  "callback-url": "https://lost-cod.net",
  "enable": true,
  "http-headers": {
    "Authorization": "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==",
    "Content-Type": "application/json",
    "x-api-key": "p7fe80848edde",
    "x-sender": "DHL"
  },
  "subscription-type": "tracking-notification-v2-purchase-order",
  "support-email-address": "Fae20@yahoo.com"
}

Response Payload

{
  "api-correlation-id": "ca5d9598-8b34-4909-8df1-7d1207e4d6d5",
  "detail": "Push Notification Updated(Enabled)",
  "status": 200,
  "title": "OK"
}

{
  "api-correlation-id": "c97e6888-937f-4726-8b85-3e20d83e3f4c",
  "detail": "Expired Access Token",
  "status": 401,
  "title": "Unauthorized"
}

{
  "api-correlation-id": "3d7f73a1-09d2-4787-8c0e-9605f33aa192",
  "detail": "The server encountered an unexpected condition.",
  "status": 500,
  "title": "Internal Server Error"
}

Timestamp Push API v2(5 operations)

POST

/subscription/timestamp

Use this operation to subscribe to either timestamp or tracking notifications.

Request Payload

{
  "status": "ACTIVE",
  "onlyNotifyAPIBookings": "true",
  "subscription-type": "timestamp-notification",
  "accountNumbers": [
    "DE01111"
  ],
  "filters": [
    {
      "modeOfTransport": "Ocean",
      "origin": [
        "DE"
      ],
      "destination": [
        "NL"
      ],
      "events": [
        "A02",
        "A04",
        "A05",
        "A12",
        "A13",
        "A17",
        "A28",
        "A29",
        "A30",
        "A31",
        "A32",
        "A34",
        "A37",
        "A39",
        "A41",
        "A42",
        "A60",
        "ARD"
      ]
    },
    {
      "modeOfTransport": "Air",
      "origin": [
        "DE"
      ],
      "destination": [
        "NL"
      ],
      "events": [
        "APT",
        "ARR",
        "ARV",
        "CAC",
        "CLC",
        "CUS",
        "DEP",
        "DEW",
        "DIH",
        "DLV",
        "EAA",
        "EAB",
        "EAC",
        "EAD",
        "EOD",
        "EPD",
        "EXD",
        "FPR",
        "FUT",
        "HBE",
        "OFD",
        "POD",
        "RCD",
        "RCS",
        "RFD",
        "RRT",
        "STU",
        "TBN"
      ]
    }
  ],
  "callback-details": {
    "support-email-address": "jdoe@example.com",
    "callback-url": "https://api.johndoe.com/shipment/timestamps",
    "http-headers": {
      "Content-type": "application/json"
    }
  }
}

Response Payload

{
  "detail": "Push Notification Created",
  "status": 200,
  "subscriptionID": "cab8469d-a8d5-41b7-9e0e-e409737d6828",
  "title": "OK"
}

{
  "api-correlation-id": "36a82884-d7d6-4094-a6cb-01af80a1ac76",
  "detail": "Expired Access Token",
  "status": 401,
  "title": "Unauthorized"
}

{
  "api-correlation-id": "11b59fdf-8643-48b8-90a3-d3aa9ae70971",
  "detail": "Server failure",
  "status": 500,
  "title": "Internal Server Error"
}

PATCH

/subscription/timestamp/{subscriber-id}

Use this operation to enable or disable the timestamp/ tracking notification subscription.

Request Payload

{
  "status": "INACTIVE"
}

Response Payload

{
  "detail": "Push Subscription Status Updated",
  "status": 200,
  "subscriptionID": "4de0b9ea-fdaf-4431-a1ee-a4044bbdb662",
  "title": "OK"
}

{
  "api-correlation-id": "007c5fa0-13b8-4195-a1d4-b14c21cf25a8",
  "detail": "Expired Access Token",
  "status": 401,
  "title": "Unauthorized"
}

{
  "api-correlation-id": "0d5e88fa-971d-41fa-bc76-dc43601dab08",
  "detail": "Server failure",
  "status": 500,
  "title": "Internal Server Error"
}

PUT

/subscription/timestamp/{subscriber-id}

Use this operation to update the filters of the subscribed timestamp/ tracking notification.

Request Payload

{
  "callback-details": {
    "callback-url": "https://ambitious-configuration.com",
    "http-headers": {
      "Authorization": "Basic QWxhZGRpbjpvcGV123456",
      "Content-Type": "application/json",
      "x-api-key": "p7fe80812456",
      "x-sender": "DHL"
    },
    "support-email-address": "Nicolette82@example.org"
  },
  "filters": [
    {
      "destination": [
        "GBFXT",
        "FRLEH"
      ],
      "events": [
        "DEP",
        "POD",
        "ARR"
      ],
      "modeOfTransport": "Road",
      "origin": [
        "DEHAM",
        "CNSHA"
      ]
    }
  ]
}

Response Payload

{
  "detail": "Push Subscription Status Updated",
  "status": 200,
  "subscriptionID": "2a02058c-ef12-4b92-8315-e04278598d4a",
  "title": "OK"
}

{
  "api-correlation-id": "57e9b09d-5dd3-4299-b243-3ca91333c47f",
  "detail": "Expired Access Token",
  "status": 401,
  "title": "Unauthorized"
}

{
  "api-correlation-id": "cc9e5c01-472c-4fb1-a3ad-0ae1eb165c6f",
  "detail": "Server failure",
  "status": 500,
  "title": "Internal Server Error"
}

GET

/subscription/timestamp/{subscriber-id}

Use this operation to retrieve the details of the corresponding subscriiption using the subscriber ID.

Request Payload

Response Payload

{
  "items": {
    "accountNumbers": [
      "DE01111"
    ],
    "callback-details": {
      "callback-url": "https://api.johndoe.com/shipment/timestamps",
      "http-headers": {
        "Content-type": "application/json"
      },
      "support-email-address": "jdoe@example.com"
    },
    "filters": [
      {
        "destination": [
          "NL"
        ],
        "events": [
          "A02",
          "A04",
          "A05",
          "A12",
          "A13",
          "A17",
          "A28",
          "A29",
          "A30",
          "A31",
          "A32",
          "A34",
          "A37",
          "A39",
          "A41",
          "A42",
          "A60",
          "ARD"
        ],
        "modeOfTransport": "Ocean",
        "origin": [
          "DE"
        ]
      },
      {
        "destination": [
          "NL"
        ],
        "events": [
          "APT",
          "ARR",
          "ARV",
          "CAC",
          "CLC",
          "CUS",
          "DEP",
          "DEW",
          "DIH",
          "DLV",
          "EAA",
          "EAB",
          "EAC",
          "EAD",
          "EOD",
          "EPD",
          "EXD",
          "FPR",
          "FUT",
          "HBE",
          "OFD",
          "POD",
          "RCD",
          "RCS",
          "RFD",
          "RRT",
          "STU",
          "TBN"
        ],
        "modeOfTransport": "Air",
        "origin": [
          "DE"
        ]
      }
    ],
    "onlyNotifyAPIBookings": "true",
    "status": "ACTIVE",
    "subscription-type": "timestamp-notification"
  },
  "subscriptionID": "7beccec8-6e80-4a63-aa45-b6bd2ab51570"
}

{
  "api-correlation-id": "71b2b41e-32e5-4df3-ace3-950aeb456913",
  "detail": "Expired Access Token",
  "status": 401,
  "title": "Unauthorized"
}

{
  "api-correlation-id": "2f2535d2-11ab-4c1e-8c26-4283a9a6ad01",
  "detail": "Server failure",
  "status": 500,
  "title": "Internal Server Error"
}

GET

/subscriptions

Use this operation to retrieve the list of available subscripion ID and subscription type under your account.

Request Payload

Response Payload

{
  "subscriptions": [
    {
      "subscription-type": "tracking-notification-v2-purchase-order",
      "subscriptionID": "67890def"
    },
    {
      "subscription-type": "tracking-notification-v2-purchase-order",
      "subscriptionID": "12345abc"
    }
  ]
}

{
  "api-correlation-id": "98c43e33-eb2a-4446-a240-24bc416a40bc",
  "detail": "Expired Access Token",
  "status": 401,
  "title": "Unauthorized"
}

{
  "api-correlation-id": "e67b0b12-eef7-4c18-8003-e8ddbf284e81",
  "detail": "Server failure",
  "status": 500,
  "title": "Internal Server Error"
}

Service Homepage: developer.dhl.com/api-reference/dgf-push-api#reference-docs-section

dhllogisticsshippingpushnotificationssupply-chain