DSV

DSV Webhook API

Subscription API for DSV push notifications covering the Invoice, Visibility, Quote, Tracking, Warehousing, Customs and Downtime events. The subscriber supplies a push URL (validated with an OPTIONS then POST probe), basic or OAuth callback credentials, and a DSV MDM or WarehouseID customer scope. Event names are DSV-proprietary (TrackingShipmentDelivered, TrackingShipmentEstimatedDeliveryChanged, TrackingShipmentPodAvailable and similar) rather than DCSA or GS1 EPCIS event types.

GitHub OpenAPI

Documentation

📖
APIReference
https://developer.dsv.com/api-details#api=es-webhook-demo-v1
📖
Documentation
https://developer.dsv.com/webhook-guide
📖
Documentation
https://developer.dsv.com/apicatalogue-generic
📖
Authentication
https://developer.dsv.com/oauth-guide

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/dsv/refs/heads/main/openapi/dsv-es-webhook-demo-v1-openapi.json

Other Resources

🔗
PostmanCollection
https://developer.dsv.com/content/DSV%20API%20(Webhook%20v1.0%20-%20samples%20with%20Bearer%20Token).postman_collection.zip

OpenAPI Specification

dsv-es-webhook-demo-v1-openapi.json Raw ↑ 
{
  "openapi": "3.0.1",
  "info": {
    "title": "Webhook (DEMO) - Air, Sea, Road(EU), Rail",
    "description": "Webhook for Invoice, Visibility, Quote, Tracking, Warehousing, Customs and Downtime Notification APIs (DEMO)",
    "version": "v1"
  },
  "servers": [
    {
      "url": "https://api.dsv.com/my-demo/webhook/v1"
    }
  ],
  "paths": {
    "/status/health": {
      "get": {
        "tags": [
          "Status"
        ],
        "summary": "Check if application is up and running",
        "description": "Check if application is up and running",
        "operationId": "Status_Get",
        "parameters": [
          {
            "name": "api-version",
            "in": "header",
            "description": "api-version",
            "schema": {
              "type": "string"
            },
            "example": 1
          },
          {
            "name": "Authorization",
            "in": "header",
            "description": "OAuth header",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": ""
          }
        }
      }
    },
    "/subscriptions/subscribe": {
      "post": {
        "tags": [
          "Webhook"
        ],
        "summary": "Subscribe to get notification of the relevant event",
        "description": "Subscribe to get notification of the relevant event (Invoice, Visibility, Quote, Tracking, Warehousing, Customs and Downtime Notification. \nThe provided push URL will be validated first by sending an OPTIONS request.  \nIf the OPTIONS request is not allowed or fails, a POST request will be sent instead\nwith the following JSON payload:\n\n{\n  \"event\": \"string\",\n  \"message\": \"string\"\n}",
        "operationId": "Webhook_Subscribe",
        "parameters": [
          {
            "name": "api-version",
            "in": "header",
            "description": "api-version",
            "schema": {
              "type": "string"
            },
            "example": 1
          },
          {
            "name": "Authorization",
            "in": "header",
            "description": "OAuth header",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "description": "Subscriber data to be saved",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SubscriberDto"
              },
              "example": {
                "subscriptionEvent": "ShipmentDeviceReading",
                "pushUrl": "http://mysite.com",
                "customerIds": {
                  "type": "string",
                  "values": []
                },
                "authenticationData": {
                  "type": "Basic",
                  "basic": {
                    "username": "test-user",
                    "password": "test-password"
                  },
                  "oAuth": {
                    "tokenGenerationUrl": "https://mytokensite.com",
                    "accessTokenRequest": {
                      "headers": [
                        {
                          "name": "client-key",
                          "value": "client-key-value"
                        }
                      ],
                      "body": {
                        "formUrlEncodedValues": [
                          {
                            "name": "client-key",
                            "value": "client-key-value"
                          }
                        ]
                      }
                    },
                    "refreshTokenRequest": {
                      "headers": [
                        {
                          "name": "client-key",
                          "value": "client-key-value"
                        }
                      ],
                      "body": {
                        "formUrlEncodedValues": [
                          {
                            "name": "client-key",
                            "value": "client-key-value"
                          }
                        ]
                      }
                    }
                  }
                },
                "headers": [
                  {
                    "name": "client-key",
                    "value": "client-key-value"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success/Failure Status"
          },
          "400": {
            "description": ""
          },
          "500": {
            "description": ""
          }
        }
      }
    },
    "/subscriptions/unsubscribe": {
      "post": {
        "tags": [
          "Webhook"
        ],
        "summary": "Unsubscribe subscription by providing subscription event name",
        "description": "Unsubscribe subscription by providing subscription event name",
        "operationId": "Webhook_Unsubscribe",
        "parameters": [
          {
            "name": "api-version",
            "in": "header",
            "description": "api-version",
            "schema": {
              "type": "string"
            },
            "example": 1
          },
          {
            "name": "Authorization",
            "in": "header",
            "description": "OAuth header",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "description": "Possible values are:\n\nGENERIC TRACKING \n- TrackingShipmentBookingSummary \n- TrackingShipmentEstimatedPickupChanged \n- TrackingShipmentEstimatedDeliveryChanged \n- TrackingShipmentEstimatedArrivalChanged \n- TrackingShipmentEstimatedDepartureChanged \n- TrackingShipmentActualArrivalChanged \n- TrackingShipmentActualDepartureChanged \n- TrackingShipmentPickedUp \n- TrackingShipmentDelivered \n- TrackingShipmentSupplierBooking \n- TrackingShipmentPodAvailable \n- TrackingShipmentExportCustomsCleared \n- TrackingShipmentImportCustomsCleared \n- TrackingShipmentGateIn \n- TrackingShipmentGateOut \n- TrackingShipmentFreightLoaded \n- TrackingShipmentFreightUnloaded \n- TrackingShipmentShipmentContainerAdded \n- TrackingShipmentShipmentStatusChanged\n\n INVOICE API \n- Invoice \n\n VISIBILITY API \n- ShipmentDeviceReading\n- ShipmentDeliveryReceipt \n\n QUOTE API \n- QuoteStatusChanged\n- QuoteRequestCreated\n- QuoteSubmitted\n- QuoteExpiringTomorrow \n\n CUSTOMS API \n- CustomsDeclarationStateUpdate \n\n DOWNTIME NOTIFICATION API \n- ApiDownTimeNotification \n\n WAREHOUSING APIs \n- WMSInboundNotificationStatusChange, \n- WMSDeliveryConfirmation, \n- WMSReceiptConfirmation, \n- WMSInventoryChange, \n- WMSOrderStatusChange, \n- WMSInventoryFull,",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UnsubscriberDto"
              },
              "example": {
                "subscriptionEvent": "string",
                "customerIds": {
                  "type": "string",
                  "values": []
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": ""
          },
          "500": {
            "description": ""
          }
        }
      }
    },
    "/subscriptions": {
      "get": {
        "tags": [
          "Webhook"
        ],
        "summary": "Get all subscriptions for the current user",
        "description": "Get all subscriptions for the current user",
        "operationId": "Webhook_GetSubscriptions",
        "parameters": [
          {
            "name": "api-version",
            "in": "header",
            "description": "api-version",
            "schema": {
              "type": "string"
            },
            "example": 1
          },
          {
            "name": "Authorization",
            "in": "header",
            "description": "OAuth header",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Returns the list of subscriptions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/SubscriberDetailsDto"
                  }
                },
                "example": [
                  {
                    "subscriptionEvent": "ShipmentDeviceReading",
                    "pushUrl": "http://mysite.com",
                    "customerIds": {
                      "type": "string",
                      "values": []
                    },
                    "authenticationData": {
                      "type": "Basic",
                      "basic": {
                        "username": "test-user",
                        "password": "test-password"
                      },
                      "oAuth": {
                        "tokenGenerationUrl": "https://mytokensite.com",
                        "accessTokenRequest": {
                          "headers": [
                            {
                              "name": "client-key",
                              "value": "client-key-value"
                            }
                          ],
                          "body": {
                            "formUrlEncodedValues": [
                              {
                                "name": "client-key",
                                "value": "client-key-value"
                              }
                            ]
                          }
                        },
                        "refreshTokenRequest": {
                          "headers": [
                            {
                              "name": "client-key",
                              "value": "client-key-value"
                            }
                          ],
                          "body": {
                            "formUrlEncodedValues": [
                              {
                                "name": "client-key",
                                "value": "client-key-value"
                              }
                            ]
                          }
                        }
                      }
                    },
                    "headers": [
                      {
                        "name": "client-key",
                        "value": "client-key-value"
                      }
                    ],
                    "createdAt": "0001-01-01T12:00:00.0000000+00:00",
                    "lastModifiedAt": "0001-01-01T12:00:00.0000000+00:00",
                    "subscribedBy": "string"
                  }
                ]
              }
            }
          },
          "500": {
            "description": "If there is an internal server error"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SubscriberDto": {
        "type": "object",
        "properties": {
          "subscriptionEvent": {
            "type": "string",
            "description": "Possible values are:\n\nGENERIC TRACKING \n- TrackingShipmentBookingSummary \n- TrackingShipmentEstimatedPickupChanged \n- TrackingShipmentEstimatedDeliveryChanged \n- TrackingShipmentEstimatedArrivalChanged \n- TrackingShipmentEstimatedDepartureChanged \n- TrackingShipmentActualArrivalChanged \n- TrackingShipmentActualDepartureChanged \n- TrackingShipmentPickedUp \n- TrackingShipmentDelivered \n- TrackingShipmentSupplierBooking \n- TrackingShipmentPodAvailable \n- TrackingShipmentExportCustomsCleared \n- TrackingShipmentImportCustomsCleared \n- TrackingShipmentGateIn \n- TrackingShipmentGateOut \n- TrackingShipmentFreightLoaded \n- TrackingShipmentFreightUnloaded \n- TrackingShipmentShipmentContainerAdded \n- TrackingShipmentShipmentStatusChanged\n\n INVOICE API \n- Invoice \n\n VISIBILITY API \n- ShipmentDeviceReading\n- ShipmentDeliveryReceipt \n\n QUOTE API \n- QuoteStatusChanged\n- QuoteRequestCreated\n- QuoteSubmitted\n- QuoteExpiringTomorrow \n\n CUSTOMS API \n- CustomsDeclarationStateUpdate \n\n WAREHOUSING APIs \n- WMSInboundNotificationStatusChange \n- WMSDeliveryConfirmation \n- WMSReceiptConfirmation \n- WMSInventoryChange \n- WMSOrderStatusChange \n- WMSInventoryFull\n\n DOWNTIME NOTIFICATION API \n- ApiDownTimeNotification",
            "example": "ShipmentDeviceReading"
          },
          "pushUrl": {
            "type": "string",
            "description": "Provide the URL where you want the data to be delivered",
            "example": "http://mysite.com"
          },
          "customerIds": {
            "$ref": "#/components/schemas/CustomerIdsDto"
          },
          "authenticationData": {
            "$ref": "#/components/schemas/AuthenticationDto"
          },
          "headers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/KeyValueDto"
            },
            "description": "Include any necessary headers. Make sure these headers match the requirements of the system receiving the data via webhook",
            "example": "Headers"
          }
        },
        "description": "Subscriber Dto"
      },
      "CustomerIdsDto": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "Type of customer identifier (MDM or WarehouseID)"
          },
          "values": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "List of customer identifier values"
          }
        }
      },
      "AuthenticationDto": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "Authentication type",
            "example": "Basic"
          },
          "basic": {
            "$ref": "#/components/schemas/BasicAuthDto"
          },
          "oAuth": {
            "$ref": "#/components/schemas/OAuthDto"
          }
        },
        "description": "Authentication object"
      },
      "BasicAuthDto": {
        "type": "object",
        "properties": {
          "username": {
            "type": "string",
            "description": "Username",
            "example": "test-user"
          },
          "password": {
            "type": "string",
            "description": "Password",
            "example": "test-password"
          }
        },
        "description": "Object to hold basic auth information"
      },
      "OAuthDto": {
        "type": "object",
        "properties": {
          "tokenGenerationUrl": {
            "type": "string",
            "description": "Token generation url",
            "example": "https://mytokensite.com"
          },
          "accessTokenRequest": {
            "$ref": "#/components/schemas/TokenRequestDto"
          },
          "refreshTokenRequest": {
            "$ref": "#/components/schemas/TokenRequestDto"
          }
        },
        "description": "Object to hold OAuth information"
      },
      "TokenRequestDto": {
        "type": "object",
        "properties": {
          "headers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/KeyValueDto"
            },
            "description": "Token request headers",
            "example": "Headers"
          },
          "body": {
            "$ref": "#/components/schemas/RequestBodyDto"
          }
        },
        "description": "TokenRequestDto to hold token request for access Token or refresh Token"
      },
      "KeyValueDto": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Name",
            "example": "client-key"
          },
          "value": {
            "type": "string",
            "description": "Value",
            "example": "client-key-value"
          }
        },
        "description": "Dto to store name value pair data (in headers, body)"
      },
      "RequestBodyDto": {
        "type": "object",
        "properties": {
          "formUrlEncodedValues": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/KeyValueDto"
            },
            "description": "List of FormUrlEncodedValues values in name-value pair",
            "example": "FormUrlEncodedValues"
          }
        },
        "description": "Dto to hold request body parameters"
      },
      "UnsubscriberDto": {
        "type": "object",
        "properties": {
          "subscriptionEvent": {
            "type": "string"
          },
          "customerIds": {
            "$ref": "#/components/schemas/CustomerIdsDto"
          }
        }
      },
      "SubscriberDetailsDto": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SubscriberDto"
          },
          {
            "type": "object",
            "properties": {
              "createdAt": {
                "type": "string",
                "description": "When the customer subscribed to the event",
                "format": "date-time"
              },
              "lastModifiedAt": {
                "type": "string",
                "description": "When the customer last modified the subscription",
                "format": "date-time"
              },
              "subscribedBy": {
                "type": "string",
                "description": "who subscribed to this event"
              }
            },
            "additionalProperties": false,
            "description": "Subscriber Details Dto"
          }
        ]
      }
    },
    "securitySchemes": {
      "apiKeyHeader": {
        "type": "apiKey",
        "name": "DSV-Subscription-Key",
        "in": "header"
      },
      "apiKeyQuery": {
        "type": "apiKey",
        "name": "DSV-Subscription-Key",
        "in": "query"
      }
    }
  },
  "security": [
    {
      "apiKeyHeader": []
    },
    {
      "apiKeyQuery": []
    }
  ]
}