Register for access to the DHL Shipment Tracking Unified Push API on the DHL API Developer Portal (developer.dhl.com) and obtain an API key.
Create a subscription by POST-ing your HTTPS callback URL and the shipment identifiers (shipment ID or account ID) to the subscription endpoint; the API returns a subscription ID and a secret.
Activate the subscription using the subscription ID and secret in a follow-up activation call as documented in the DHL Push API 101 guide.
On each inbound push, parse the JSON payload for status events, location updates, and estimated delivery time; acknowledge with HTTP 200 to prevent retries.
Handle DHL's retry schedule: if delivery fails, DHL retries after approximately 1 hour, then approximately 6 hours; after the third failed attempt no further retries occur and a technical contact is notified by email.
Monitor the subscription health endpoint or error notifications to detect silently dropped subscriptions and recreate them proactively.
Known gotchas
As of mid-2025 DHL Express push subscription by shipment ID and by account ID availability varies by service type — confirm which DHL service (Express vs eCommerce Europe vs Global Forwarding) supports the subscription method you need before building.
Failing to return HTTP 200 within DHL's timeout window causes the delivery to be counted as failed, consuming your retry budget — keep handler logic asynchronous so acknowledgment is immediate.
DHL issues the secret only at subscription creation time and does not re-expose it; store it securely at creation or you will need to delete and recreate the subscription.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp