Webhook Documentation
On this page the steps to setup a webhook with is explained.
Webhook - Generic Tracking
A webhook is a reverse API, that proactively sends notifications to the provided endpoint. The myDSV Webhook will not send any sensitive data. To get the actual shipment data the Tracking API needs to be used.
Setting up a webhook
The webhooks can be created in myDSV with the following steps:
1. Request DSV to enable webhook feature via developer.support@dsv.com
2. Login using your API credentials at https://mydsv.com/new/settings/subscriptions
3. After login you will see the below screen:
4. Click “edit all notifications” or click on “add subscription”.
5. Select the subscription you want to receive notifications for via the webhook by toggling the on / off button and click edit notification.
6. Select “Public API Webhook” within Recipient field
a. This option is only available if granted by developer.support@dsv.com
7. Add your endpoint in the field next to “Public API Webhook” and click add
a. myDSV will validate that your provided endpoint is a valid URL.
8. The endpoint is now configured for the given notification.
9. Click Save at the bottom of the window.
Webhook notifications are always sent as the event happens.
It is also possible to setup the Webhook on a shipment level.
This is done with the following steps:
1. Login at myDSV with your API credentials.
2. Open the shipment you want to add Webhook to
3. Click on the bell (see below)
4. Select the subscription you want to receive notifications for via the webhook by toggling the “Yes” button.
5. Select “Public API Webhook” within Recipient field
a. This option is only available if granted by developer.support@dsv.com
6. Add your endpoint in the field next to “Public API Webhook” and click add
a. myDSV will validate that your provided endpoint is a valid URL.
7. The endpoint is now configured for the given notification.
8. Click Save at the bottom of the window.
Webhook notifications are always sent as the event happens
Notification subscription options
Explanation on how events are triggered:
For “estimated” notifications:
For Air/Sea/Rail we’re sending notifications when estimated date was changed. It means – there was already some date set and then it was changed
For Road we’re sending notifications even when particular date was set for the first time
Setting up the endpoint
The client setting up the endpoint is free to define how the URL should look according to own requirements. You can accept all the webhooks at one endpoint or setup multiple endpoint (one for each event)
We recommend the following:
Only send data over HTTPS
Add a security token to the URL to verify that only requests coming from DSV is allowed
Whitelist the DSV IP-address the request will be sent from
Payload structure
Payload structure of webhook:
Event (See event codes with notification subscription options section)
Timestamp (of when the webhook was triggered)
Shipment id
Booking id
Bookingparty id
Example:
Response
DSV expects to receive an HTTP 200 response code from your endpoint.
Webhook setup - Generic Invoice
A webhook is a reverse API, that proactively sends the Invoice data to to the designated endpoint.
When you activate the webhook for Invoice you will receive data on all the MDM numbers, which are associated with your API user.
Upon activation of the webhook for Invoice, you will receive data pertaining to all MDM numbers associated with your API user.
Invoice Webhook - Subscribe
POST URL: https://api.dsv.com/my/invoicedemo/v1/invoices/subscribe
Specify the Push URL: Provided the URL where you want the data to be delivered.
AuthenticationData: We only accept Basic authentication (username and password)
Replace "test-user" with your actual username and "test-password" with your real password.
Headers: Include any necessary headers. Make sure these headers match the requirements of the system receiving the webhook.
Invoice Webhook - Test
After setting up the webhook, test it to ensure it's functioning as expected. After subscribing, an invoice sample will be sent to the defined endpoint.
Invoice Webhook - Unsubscribe
To unsubscribe the invoice webhook, post an API call to the below URL, using your Basic authentication, await response "200 OK".
POST URL: https://api.dsv.com/my/invoicedemo/v1/invoices/unsubscribe
Webhook is now unsubscribed.
Webhook setup - Visibility
URL: https://api.dsv.com/my/visibilitydemo/v1/shipments/subscribe
Visibility Webhook - Subscribe
subscriptionEvent
Include the event you want to subscribe to ShipmentDeviceReading or ShipmentDeliveryReceipt. Only subscribe to one event at a time.
Specify the Push URL: Provided the URL where you want the data to be delivered.
AuthenticationData: We only accept Basic authentication (username and password.)
Replace "test-user" with your actual username and "test-password" with your real password.
Headers: Include any necessary headers. Make sure these headers match the requirements of the system receiving the webhook.
Visibility Webhook - Test
After setting up the webhook, test it to ensure it's functioning as expected. Trigger the event that the webhook is subscribed to and verify that the Data is delivered to the specified URL with the correct authentication and headers.
Visibility Webhook - Unsubscribe
Depending on which webhook you want to unsubscribe, post an API call to the below URL. Specify the subscriptionEvent, use your Basic authentication and await response "200 OK".
Webhook is now unsubscribed.
URL: https://api.dsv.com//my/visibilitydemo/v1/shipments/unsubscribe/{subscriptionEvent}