Process

When registering a notification, the receiving service must be alive and able to respond. Each step of the process is detailed below.

A notification hook is registered by posting to the following api endpoint.

POST https://logisticsapi.dfds.com/api/notification

Attributes

Registration Challenge

When a notification hook is registered, a challenge is sent to the provided notification delivery endpoint.

POST
X-NotificationEndpointChallenge
[nonce]

The request will contain a single plain text nonce in the body. The endpoint must return a HMAC-SHA256 hash, using the provided secret, of the nonce also in the body of the response within 10 seconds to validate the endpoint configuration. The hash should be returned as a base64 encoded string.

Client Errors

HTTP/1.1 400 Bad Request
Missing registration data

HTTP/1.1 400 Bad Request
Delivery format must be specified. Example: application/json.

HTTP/1.1 400 Bad Request
A secret must be specified for your notification hook. This secret is used to sign notifications so you can prevent notificatinos from unauthorized sources.

HTTP/1.1 400 Bad Request
Notification url must be specified. Notifications will be delivered to this url.

HTTP/1.1 400 Bad Request
You have specified that SSL must be validated when delivering notifications, but the provided notification url is not https.

HTTP/1.1 400 Bad Request
An event type must be specified. Possible values are: {eventTypes}.

HTTP/1.1 400 Bad Request
Event type '{eventType}' is not supported. Please specify one of the following event types: {eventTypes}.

HTTP/1.1 400 Bad Request
The event type '{eventType}' does not support a delivery format of {deliveryFormat}. Supported delivery formats are: XX

HTTP/1.1 400 Bad Request
The notification endpoint did not respond within 10 seconds.

HTTP/1.1 400 Bad Request
Error cummunicating with remote endpoint

HTTP/1.1 400 Bad Request
The hashcode challenge is incorrect

HTTP/1.1 400 Bad Request
Received a non-success status code from notification endpoint

Security

Notification posts are signed using HMAC-SHA256. You should verify the signature of received notifications to authenticate the source of the information. The secret used to sign notifications is configured when registering a notification hook. The signature is provided as a header value when posting the notification:

X-Signature: f7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8
X-SignatureAlgorithm: HMAC-SHA256

Additionally, a notification delivery contains headers identifying the triggering notification hook and a unique id for the delivery.

User-Agent: Velocity/2.5.7.1
X-NotificationHookId: 314
X-NotificationDeliveryId: 256134
X-NotificationDeliveryTryId: 5487965

The notification signature can be validated using the following sample code

• C#
• Ruby

    
        using System.Text;
        using System.Security.Cryptography;

        public static async Task<bool> ValidateSignatureAsync(HttpResponseMessage message, string secret)
        {
            using (var algorithm = new HMACSHA256(Encoding.UTF8.GetBytes(secret)))
            {
                var content = await message.Content.ReadAsStringAsync();
                var byteContent = Encoding.UTF8.GetBytes(content);
                var calculatedSignature = algorithm.ComputeHash(byteContent);

                IEnumerable<string> signatureResults;
                message.Headers.TryGetValues("X-Signature", out signatureResults);
                var providedSignature = Convert.FromBase64String(signatureResults.FirstOrDefault());
                return calculatedSignature.SequenceEqual(providedSignature);
            }
        }
    

    
        require 'openssl'
        require 'base64'

        secret = "secret"
        challenge = "challenge"
        signature  = OpenSSL::HMAC.digest('sha256', secret, challenge)
        encodedSignature = Base64.urlsafe_encode64(signature)
    

Delivery Guarantee

We will retry notification delivery if the notification endpoint fails. A delivery is considered delivered when a 200-range HTTP status code is returned within 10 seconds. The request will contain a single plain text nonce. The endpoint must return a HMAC-SHA256 hash, using the provided secret, of the nonce within 10 seconds to validate the endpoint configuration.
The hash should be returned as a base64 encoded string.
If successfull delivery is still not possible, we will mark the delivery as failed. You can use the auditing and debugging api's to investigate the problem.

Deliveries are retried according to the following approximate wait times (ie. time waited after the previous delivery attempt)

• 00:00:00
• 00:00:15
• 00:05:00
• 00:10:00
• 00:15:00
• 00:20:00
• 00:25:00
• 00:30:00
• 00:35:00
• 00:40:00

Listing registered notifications

GET https://logisticsapi.dfds.com/api/notification?page={page}

Paging

The result is paged with max 20 items pr page. Use the response header 'X-HasMoreItems' to determine whether additional pages are available. Pages are indexed starting at 1. The page number to retrieve. If no page page is specified, the first page is returned.

X-HasMoreItems: True

Client Errors

HTTP Status 400 if the provided page is less than 1.

HTTP/1.1 400 Bad Request
The page numbering starts a '1', but you specified 0. Please try again using a page number of 1 or larger

Single registered notification

GET https://logisticsapi.dfds.com/api/notification/{hookId}

Response

Attributes

Example

        {
            "$id": "1",
            "createdDate": "2017-12-02T12:21:09",
            "lastUpdatedDate": "2017-12-03T17:37:41",
            "id": 10231,
            "event": "TrackingUpdated",
            "notificationUrl": "https://company.com/events/trackingUpdate",
            "deliveryFormat": "application/json",
            "requireValidSSL": true,
            "secret": "WUPuBhdEdw6Pn92fAKAcrFRv"
        }
    

Changing parameters

POST https://logisticsapi.dfds.com/api/notification/{hookId}

Request

Attributes

Example

        
                {
                    "event": "TrackingUpdated",
                    "notificationUrl": "https://company.com/events/trackingUpdate",
                    "deliveryFormat": "application/json",
                    "requireValidSSL": true,
                    "secret": "WUPuBhdEdw6Pn92fAKAcrFRv"
                }
            
        

Client Errors

HTTP/1.1 404 Not Found
Changing event type of a registered notification hook is not supported. Please delete this notification hook and create a new one instead.

Listing deliveries

A list of deliveries can be listed for a specific notification hook within a time range. The startDate and endDate parameters are in UTC time. The result is paged with max 20 items pr page. Use the response header 'X-HasMoreItems' to determine whether additional pages are available. Pages are indexed starting at 1.

GET https://logisticsapi.dfds.com/api/notification/{hookId}/delivery?startDate={startDate}&endDate={endDate}&page={page}

Response

The response is a list of Deliveries.

    
{
    "id": 1231123,
    "eventTriggerTime": "2017-12-05T07:51:02",
    "status": "Completed",
    "tries": [
        {
            "$id": "2",
            "time": "2017-12-05T07:51:17",
            "isSuccess": true,
            "id": "8762315"
        }
    ]
}
    

Client Errors

HTTP/1.1 404 Not Found
Could not find a registered notification hook with id '324'

HTTP/1.1 400 Bad Request
The provided end date must be greater than the provided start date. You provided Start {startDate}, End: {endDate}

HTTP/1.1 400 Bad Request
The span between the start and end date must not be greter than 24 hours. You provided Start {startDate}, End: {endDate}, Span: {span}

Single delivery

Gets an audit log for notifications delivered on the specified hook. Use this to debug a notification setup.

GET https://logisticsapi.dfds.com/api/notification/{hookId}/delivery/{deliveryId}

Attributes

Each delivery try is defined with the following set of attributes

Client Errors

HTTP/1.1 404 Not Found
Could not find a registered notification hook with id '324'

HTTP/1.1 404 Not Found
Could not find a notification delivery with id '234901' for notification hook with id '324'

Getting delivery details

Gets detailed request and response information for a specific delivery try. Use this to debug an issue with a registered notification hook. This information is available up to 14 days after the delivery try.

GET https://logisticsapi.dfds.com/api/notification/{hookId}/delivery/{deliveryId}/tries/{tryId}/details

Attributes

The details of an individual delivery try include the following set of attributes

Client Errors

HTTP/1.1 404 Not Found
Could not find a registered notification hook with id '324'

HTTP/1.1 404 Not Found
Could not find a notification delivery with id '234901' for notification hook with id '324'

HTTP/1.1 404 Not Found
Could not find a notification delivery try with id '1231' for delivery id '234901' for notification hook with id '324'

Re-deliver notification

Triggers resubmission of a previous notification delivery. This functionary is available up to 14 days after a notification delivery has either failed or completed. The notification will be delivered to the currently registered endpoint of the notification hook.

POST https://logisticsapi.dfds.com/api/notification/{hookId}/delivery/{deliveryId}/resend

Client Errors

HTTP/1.1 404 Not Found
Could not find a registered notification hook with id '324'

HTTP/1.1 404 Not Found
Could not find a notification delivery with id '234901' for notification hook with id '324'

Booking Flow Hooks

These events are triggered when a booking operation state changes according to Booking Flow. The event names are as follows: Booking Received, Booking Approved, Booking Rejected, Booking Cancelled, Booking Withdrawn.

For details on booking flow and event message contents, see Booking Flow.

Booking Collection ATA Changed

This event is triggered when the Actual Time of Arrival changes on a Collection Location on a Booking.

            
{
  "$id": "1",
  "eventType": "Booking Collection ATA Changed",
  "bookingExternalId": "B24266084965",
  "locationExternalId": "4020",
  "bookingId": 14287212,
  "trackingTime": "2024-11-07T07:08:00",
  "equipmentNumber": "BM7686",
  "truckNumber": "M15003"
}
                
            

Booking Collection ATD Changed

This event is triggered when the Actual Time of Departure changes on a Collection Location on a Booking.

                
{
  "$id": "1",
  "eventType": "Booking Collection ATD Changed",
  "bookingExternalId": "B24266084965",
  "locationExternalId": "4020",
  "bookingId": 14287212,
  "trackingTime": "2024-11-07T07:08:00",
  "equipmentNumber": "BM7686",
  "truckNumber": "M15003"
}
                
            

Booking Delivery ATA Changed

This event is triggered when the Actual Time of Arrival changes on a Delivery Location on a Booking.

                
{
  "$id": "1",
  "eventType": "Booking Delivery ATA Changed",
  "bookingExternalId": "B24266084965",
  "locationExternalId": "4020",
  "bookingId": 14287212,
  "trackingTime": "2024-11-07T07:08:00",
  "equipmentNumber": "BM7686",
  "truckNumber": "M15003"
}
                
            

Booking Delivery ATD Changed

This event is triggered when the Actual Time of Departure changes on a Delivery Location on a Booking.

                
{
  "$id": "1",
  "eventType": "Booking Delivery ATD Changed",
  "bookingExternalId": "B24266084965",
  "locationExternalId": "4020",
  "bookingId": 14287212,
  "trackingTime": "2024-11-07T07:08:00",
  "equipmentNumber": "BM7686",
  "truckNumber": "M15003"
}
                
            

Booking Actual Equipment No. Changed

This event is triggered when the Equipment used for Collection or Delivery on any location changes.

                
{
  "$id": "1",
  "eventType": "Booking Actual Equipment No. Changed",
  "BookingExternalId": "B24266084965",
  "bookingId": 14287213,
  "subBookings": [
    {
      "$id": "2",
      "collectionLocationExternalId": "4020",
      "collectionEquipmentNumber": "CF7732",
      "collectionTruckNumber": "M15003",
      "deliveryLocationExternalId": "1337",
      "deliveryEquipmentNumber": "CF7732",
      "deliveryTruckNumber": "M15003"
    },
    {
      "$id": "3",
      "collectionLocationExternalId": "133222",
      "collectionEquipmentNumber": "CSO271",
      "collectionTruckNumber": "ETX581",
      "deliveryLocationExternalId": "133",
      "deliveryEquipmentNumber": "H358",
      "deliveryTruckNumber": "ETX581"
    }
  ]
}
                
            

Booking Tracking

This event is triggered when the last known position of a subboking changes. See Booking Tracking for more details.