Webhooks

Webooks are a convenient way to notify external systems of booking events that occur from within Mobiledock.

Creating a Webhook

To create a webhook, visit the Integration Hub and select the organisation you wish to create a token for. Navigate to the Webhooks page. From here, you will be able to manage webhooks for your organisation.

Integration Hub

Environment	URL
Production	integrations.mobiledock.com
Staging	integrations.staging.mobiledock.com

Configuration

When creating a webhook, there are a number of settings that can be configured:

Name: The name of your webhook
Description (Optional): A description of your webhook.
Webhook URL: The URL that webhooks should be sent to.
Headers (Optional): Headers can be added to each webhook that is sent from Mobiledock. Any headers that are added must be prefixed with x-, with the exception of the Authorization header, which does not require a prefix.
Booking Events: The booking events which should cause the webhook to fire.
Status Events: Specific statuses that should cause the webhook to fire.
Include History: Toggle whether the webhook payload contains the booking history.
Include Comments: Toggle whether the webhook payload contains the booking comments.
Failure Notification Emails (Optional): Emails which will receive a notification if the webhook fails.

Webhook Payload

Payload Properties

All times are represented in UTC time. Timezones of organisations are provided to assist with conversion.

Properties

Name	Description
eventTriggeredAt `Timestamp`	The time at which the event was triggered at.
createdAt `Timestamp`	The time at which the booking was created.
modifiedAt `Timestamp`	The time at which the booking was last modified.
types `[WebhookType!]`	The types of changes that have occurred on the booking for this webhook to trigger.
id `UUID`	The ID of the booking.
pin `Int`	The PIN code. Only a booking with a space has a PIN code. This code is guaranteed to be unique within 72 hours forward or backwards from the booking. Otherwise, no uniqueness is guaranteed.
location `Organisation`	The location for the booking.
carrier `Organisation`	The carrier for the booking.
area `Area`	The area of the booking. May be requested or actual, depending on the status of the booking. Null if the booking is submitted but no area has been provided.
space `Space`	The space assigned to this booking. Will not be present if the booking hasn't been approved.
requestedTime `Timestamp`	The requested time of the booking.
bookedTime `Timestamp`	The booked time of the booking. Will not be present if the booking hasn't been approved.
duration `Int`	The duration of the booking, in minutes.
vehicle `Vehicle`	The vehicle on the booking.
tasks `[Task!]`	A list of tasks on the booking.
status `Status`	The present status of the booking.
bookingHistory `[History!]`	The history of a booking, ordered from earliest to latest.
fields `[FieldData!]`	The current field values for the booking.
driver `Driver`	The driver on the booking.
bookingType `BookingType`	The type of the booking.
comments `[Comment!]`	A list of comments on the booking.
carrierCore `CoreDetails`	The core details associated with the carrier on the booking.

Example Payload

{
  "eventTriggeredAt": "2024-08-20T02:35:30Z",
  "createdAt": "2024-08-20T02:35:30Z",
  "modifiedAt": "2024-08-20T02:35:30Z",
  "types": [
    "FlowStatusUpdate",
    "Created",
    "AssignedSpace",
    "RequestedTimeUpdate",
    "TasksChange",
    "VehicleChange"
  ],
  "id": "MDB-24-8X4K-7G5J",
  "pin": "10523",
  "location": {
    "id": "c875c903-7d98-4ee5-852e-2c8a7b435484",
    "name": "My Organisation",
    "connectionAttributes": null,
    "timezone": "Australia/Melbourne",
    "address": {
      "address1": "123 Main St",
      "address2": "",
      "city": "Melbourne",
      "postal": "3000",
      "region": "",
      "country": "Australia"
    }
  },
  "carrier": {
    "id": "c875c903-7d98-4ee5-852e-2c8a7b435484",
    "name": "My Organisation",
    "connectionAttributes": null,
    "timezone": "Australia/Melbourne",
    "address": {
      "address1": "123 Main St",
      "address2": "",
      "city": "Melbourne",
      "postal": "3000",
      "region": "",
      "country": "Australia"
    }
  },
  "area": {
    "description": "",
    "id": "28177157-9615-49a0-8327-3d0fbb8g40c6",
    "name": "West Dock"
  },
  "space": {
    "id": "2187c155-cc57-4cca-8838-db72a4e98bb9",
    "name": "Bay 01"
  },
  "requestedTime": "2024-08-20T02:35:00Z",
  "bookedTime": "2024-08-20T02:35:00Z",
  "duration": 60,
  "vehicle": {
    "id": "b9ce5dcf-83f7-4548-8d38-ca2be7f073b0",
    "name": "Van"
  },
  "tasks": [
    {
      "id": "MDT-01-DP0Y-9F2L",
      "sender": {
        "id": "5br33d6r-2e40-4hdd-a5ac-628w44fef74f",
        "name": "Supplier 1",
        "connectionAttributes": null,
        "timezone": "Australia/Melbourne",
        "address": {
          "address1": "Level 1 Suite 5 150 Albert Rd",
          "address2": "",
          "city": "South Melbourne",
          "postal": "3205",
          "region": "VIC",
          "country": "Australia"
        }
      },
      "senderCore": null,
      "receiver": {
        "id": "c875c903-7d98-4ee5-852e-2c8a7b435484",
        "name": "My Organisation",
        "connectionAttributes": null,
        "timezone": "Australia/Melbourne",
        "address": {
          "address1": "123 Main St",
          "address2": "",
          "city": "Melbourne",
          "postal": "3000",
          "region": "",
          "country": "Australia"
        }
      },
      "receiverCore": {
        "ids": ["00000123"],
        "name": "Vendor #123"
      },
      "direction": "Inbound",
      "loads": [
        {
          "id": "99746ak5-417d-4f4p-9f74-1c74af80eb5d",
          "name": "Pallets",
          "quantity": 10,
          "loadTag": null
        }
      ],
      "bookingOptions": [],
      "document": {
        "id": "PO1234",
        "description": "",
        "attributes": {},
        "status": null,
        "type": null
      },
      "documentId": "PO1234"
    }
  ],
  "status": {
    "id": "6eedi425-8a84-40i5-8f3d-6544da943644",
    "name": "Approved",
    "type": "Approved"
  },
  "bookingHistory": null,
  "fieldData": [
    {
      "field": {
        "id": "715b4fe4-86cc-4202-b469-0da7bd891ccc",
        "name": "Field 1"
      },
      "value": null
    },
    {
      "field": {
        "id": "22efe73c-36b3-435b-bb1k-934acbe14ff8",
        "name": "Field 2"
      },
      "value": null
    }
  ],
  "driver": null,
  "bookingType": "Standard",
  "comments": null,
  "carrierCore": {
    "ids": ["00000123"],
    "name": "Vendor #123"
  }
}

Webhook Response

A webhook should be responded to with a success status code (a code within the 2xx range) in order to be successfully received. A webhook will timeout after 25 seconds of waiting for a response, in which case it will be counted as failed.

Failed Webhook Requests

If a webhook is responded to with a non-success status code (any status code outside of the 2xx range), or a webhook fails to connect at all, it will be retried after a short delay (5-30 minutes). A webhook will be retried up to 3 times. If a webhook fails more than 3 times, it will be disabled, and will need to be manually reenabled by Mobiledock.

The response content and status code of the last failed response will be recorded.

Creating a Webhook​

Configuration​

Webhook Payload​

Payload Properties​

Example Payload​

Webhook Response​

Failed Webhook Requests​