Webhook Documentation

Webhooks allow DSV to automatically send event notifications to your system (your pushUrl) when something changes. Examples include tracking milestones, quote updates, invoice availability, visibility updates, customs status changes, and warehousing events.

For event-wise payload examples, refer to: Webhook Response Examples

Getting Started in 5 Minutes OAuth 2.0

  1. Choose an event you want to receive (see Event Catalogue below).
  2. Prepare your endpoint (pushUrl) to accept HTTPS POST requests and JSON payloads.
  3. Get access to DSV APIs: OAuth 2.0 token + your DSV-Subscription-Key for the target environment.
  4. Create a subscription using the Subscribe API with subscriptionEvent, pushUrl, and authenticationData.
  5. Validate delivery using your endpoint logs and the Response Examples page.

Before you start: To use the Webhook APIs, you need:

  • A DSV-Subscription-Key for the Webhook API (environment specific).
  • A valid OAuth 2.0 access token to authenticate your API requests.

Subscription keys are environment specific:
Demo keys work only in Demo, QA keys only in QA, and Production keys only in Production.

Demo: Subscription keys can be generated directly in the Developer Portal after subscribing to the product.
QA / Production: Subscription keys are provided by DSV Support. Email developer.support@dsv.com with the environment (QA or Production). Our support team will respond once the key is ready.

How Webhooks Work
A simple explanation of what happens after you subscribe

A webhook is a notification sent from DSV to your system when an event occurs. Once subscribed, DSV sends an HTTPS POST request with a JSON payload to your pushUrl.

  • Subscriptions are created via APIs (subscribe / unsubscribe / list).
  • Webhooks send notifications for new events after the subscription is created.
  • Your endpoint should return a 2xx status code once the payload is accepted.
Authorization (OAuth 2.0)
Token-based access for DSV APIs and secure delivery to your pushUrl

DSV Webhook APIs require OAuth 2.0 token-based authentication. Include a valid access token in your API requests:

Authorization: Bearer <access_token>

When subscribing, you can provide authenticationData so DSV can securely deliver webhook data to your endpoint (by requesting a token from your token generation URL).

Common headers:

  • Authorization: Bearer <access_token>
  • DSV-Subscription-Key: <your_subscription_key>
API Operations
Subscribe, unsubscribe, list subscriptions, and health check
Operation Method Path Purpose
Health GET /status/health Check if the webhook service is available
Subscribe POST /subscriptions/subscribe Create a subscription for a specific event
Unsubscribe POST /subscriptions/unsubscribe/{subscriptionEvent} Remove a subscription for a specific event
List subscriptions GET /subscriptions Get all subscriptions for the current user

Tip: If you need to change your pushUrl, unsubscribe and subscribe again with the updated URL.

Subscribe (Create a Subscription)
Minimum required fields + sample request

To subscribe, provide:

  • subscriptionEvent: the event name (case-sensitive)
  • pushUrl: your receiving endpoint URL (HTTPS, accepts POST + JSON)
  • authenticationData: OAuth configuration for secure delivery to your endpoint
  • headers (optional): any additional headers your endpoint requires
POST /subscriptions/subscribe
{ "subscriptionEvent": "TrackingShipmentDelivered", "pushUrl": "https://example.yourcompany.com/dsv/webhook", "authenticationData": { "type": "oauth", "oAuth": { "tokenGenerationUrl": "https://example.yourcompany.com/oauth/token", "accessTokenRequest": { "headers": [ { "name": "Content-Type", "value": "application/x-www-form-urlencoded" } ], "body": { "formUrlEncodedValues": [ { "name": "client_id", "value": "YOUR_CLIENT_ID" }, { "name": "client_secret", "value": "YOUR_CLIENT_SECRET" }, { "name": "grant_type", "value": "client_credentials" } ] } } } } }

The request schema and accepted values are defined in the Webhook API specification.

Event Catalogue
Expand each group to view event names used as subscriptionEvent
Tracking Events
Shipment milestones, ETAs/ATAs, customs, containers, freight status
TrackingShipmentBookingSummary
TrackingShipmentPodAvailable
TrackingShipmentEstimatedPickupChanged
TrackingShipmentEstimatedDeliveryChanged
TrackingShipmentEstimatedArrivalChanged
TrackingShipmentEstimatedDepartureChanged
TrackingShipmentActualArrivalChanged
TrackingShipmentActualDepartureChanged
TrackingShipmentPickedUp
TrackingShipmentDelivered
TrackingShipmentSupplierBooking
TrackingShipmentExportCustomsCleared
TrackingShipmentImportCustomsCleared
TrackingShipmentGateIn
TrackingShipmentGateOut
TrackingShipmentFreightLoaded
TrackingShipmentFreightUnloaded
TrackingShipmentShipmentContainerAdded
TrackingShipmentShipmentStatusChanged

Use the exact event name as the subscriptionEvent value when subscribing.

Quote Events
Updates related to quote requests, submission, status, and expiry
QuoteRequestCreated
QuoteSubmitted
QuoteStatusChanged
QuoteExpiringTomorrow

Use the exact event name as the subscriptionEvent value when subscribing.

Invoice Events
Notifications related to invoice availability
Invoice

Use the exact event name as the subscriptionEvent value when subscribing.

Visibility Events
Device readings and delivery receipt notifications
ShipmentDeviceReading
ShipmentDeliveryReceipt

Note: Access to visibility data may depend on compatible devices linked to your shipment.

Use the exact event name as the subscriptionEvent value when subscribing.

Customs Declaration Events
Customs declaration status updates
CustomsDeclarationStateUpdate

Use the exact event name as the subscriptionEvent value when subscribing.

Warehousing (WMS) Events
Inventory, order status, receipt and delivery confirmations
WMSDeliveryConfirmation
WMSReceiptConfirmation
WMSInventoryChange
WMSOrderStatusChange
WMSPreAdviceStatusChange
WMSInventoryFull

Use the exact event name as the subscriptionEvent value when subscribing.

API Downtime Notifications
Notifications about service interruptions or maintenance windows
ApiDownTimeNotification

Downtime notifications are subscribed in the same way as any other event (subscribe with the event name and your pushUrl).

Use the exact event name as the subscriptionEvent value when subscribing.

Transport Mode Compatibility
Supported transport modes for each webhook event

Not all webhook events are applicable to every transport mode. The table below shows which transport modes support each event.

Event Trigger When / On Transport Mode Webhook Event Name
Booking summary When booking was submitted Road, Air, Sea, Rail TrackingShipmentBookingSummary
Estimated pickup On estimated pickup event change Road, Air, Sea, Rail, Xpress TrackingShipmentEstimatedPickupChanged
Estimated delivery On estimated delivery event change Road, Air, Sea, Rail, Xpress TrackingShipmentEstimatedDeliveryChanged
Estimated arrival changed On ETA event change Air, Sea, Rail, Xpress TrackingShipmentEstimatedArrivalChanged
Estimated departure changed On ETD event change Air, Sea, Rail, Xpress TrackingShipmentEstimatedDepartureChanged
Actual arrival changed On arrival event change Air, Sea, Rail, Xpress TrackingShipmentActualArrivalChanged
Actual departure changed On departure event change Air, Sea, Rail, Xpress TrackingShipmentActualDepartureChanged
Picked up On pickup confirmation Road, Air, Sea, Rail, Xpress TrackingShipmentPickedUp
Delivered On delivery confirmation Road, Air, Sea, Rail, Xpress TrackingShipmentDelivered
Supplier booking When supplier booking was submitted Road, Air, Sea, Rail TrackingShipmentSupplierBooking
POD available When Proof of Delivery is available Road TrackingShipmentPodAvailable
Export customs cleared On export customs clearance Air, Sea, Rail TrackingShipmentExportCustomsCleared
Import customs cleared On import customs clearance Air, Sea, Rail TrackingShipmentImportCustomsCleared
Shipment status changed On shipment status update Road, Air, Sea, Rail TrackingShipmentShipmentStatusChanged
Gate in On gate-in event Sea TrackingShipmentGateIn
Gate out On gate-out event Sea TrackingShipmentGateOut
Freight loaded On freight loaded event Sea TrackingShipmentFreightLoaded
Freight unloaded On freight unloaded event Sea TrackingShipmentFreightUnloaded
Shipment container added On container added to shipment Sea TrackingShipmentShipmentContainerAdded

Use the exact event name as the subscriptionEvent value when subscribing.

Payload Examples
Example payloads for each webhook event

Webhook payloads vary by event. Use the examples page to view sample responses for each event:

Webhook Response Examples

Select the relevant tab to view samples by event.

Troubleshooting
Common reasons for missing webhooks or subscription errors
  • No webhook received: confirm your pushUrl is reachable over HTTPS and accepts POST requests.
  • Delivery failures: ensure your endpoint returns a 2xx status code once the payload is accepted.
  • Subscribe returns 400: verify the subscriptionEvent is valid and case-sensitive and the body matches the Webhook API specification.
  • Authentication errors: verify OAuth tokens for DSV API calls and the OAuth configuration used for delivery (authenticationData).
Support
How to get help and what to include

For support, contact: developer.support@dsv.com

You may also find answers to common questions in the Developer Portal FAQs , covering authentication, subscriptions, and general API usage.

Please include: environment (Demo/QA/Production), subscriptionEvent(s), pushUrl domain (do not share secrets), timestamp of the test, and any error message returned by the API.