Webhooks

Experimental Feature

Webhooks is currently an experimental feature in beta. It requires manual setup by the Opendock team and is not available for self-service registration at this time. Features, payload formats, and behavior may change without prior notice.

Webhooks in Opendock Nova allow your systems to receive real-time HTTP notifications when specific database operations occur on your warehouse entities. Instead of polling the API for changes, Opendock will automatically send an HTTP POST request to your specified endpoint whenever a Create, Update, or Delete operation happens on a monitored entity.

Quick Start Guide

Getting started with Opendock webhooks takes just a few steps:

1. Identify your use case — Determine which entity (e.g., Appointment, AssetVisit, Document) and which operation (Create, Update, or Delete) you need to monitor.
2. Prepare your endpoint — Set up an HTTPS endpoint that can receive POST requests and respond with HTTP 200 or 204 quickly.
3. Contact your account manager — Reach out to your Opendock account manager with:
   • Your target URL (HTTPS endpoint)
   • Any custom headers (e.g., authentication tokens)
   • The desired warehouses to monitor
   • The entity type and operation to monitor
4. Start receiving events — Once the Opendock team registers your webhook, notifications will begin flowing to your endpoint in real time.

tip

Your endpoint should acknowledge receipt quickly (return 2xx) and handle business logic asynchronously. This ensures webhook delivery is not blocked by slow processing.

How Webhooks Work

When an operation occurs on a monitored entity in Opendock:

1. The system detects the database operation (Create, Update, or Delete).
2. The webhook engine constructs a JSON payload containing the entity type, operation, and full entity data.
3. An HTTP POST request is sent to the registered target URL with the configured headers.
4. The customer endpoint receives the payload and should respond with a 2xx status code.

Registration Process

Since webhooks are currently managed by the Opendock team, the registration follows a manual workflow:

Step 1: Request Webhook Registration

Contact your Opendock account manager and provide the following information:

Parameter	Required	Description
Target URL	Yes	The HTTPS endpoint where notifications will be sent
Custom Headers	No	A JSON object of HTTP headers to include in every request (e.g., authentication)
Authentication Token	No	A fixed/static token to be included in headers (e.g., Bearer token)
Warehouse ID or Org ID	Yes	The warehouse or organization the webhook applies to
Entity Type	Yes	The entity to monitor (e.g., Appointment, AssetVisit, Dock)
Operation	Yes	The operation to monitor: Create, Update, or Delete

Step 2: Opendock Registers the Webhook

The Opendock team will configure the webhook in the system and confirm registration with you.

Step 3: Webhook Becomes Active

Once registered, the webhook starts sending notifications immediately for matching events. You will receive an HTTP POST request to your target URL each time the specified operation occurs on the specified entity within your warehouse.

One Webhook Per Combination

Each webhook registration is scoped to one entity + one operation + one warehouse combination. If you need to monitor multiple operations on the same entity (e.g., Create and Update on Appointment), you will need separate webhook registrations for each.

Entity Payload Examples

Below are short examples of the data object you can expect for some of the most commonly used entities.

Appointment

{
  "entity": "Appointment",
  "operation": "Create",
  "data": {
    "id": "0347e2b7-f9b4-4c1d-8774-bdbec96cc75b",
    "createDateTime": "2026-02-11T19:40:02Z",
    "lastChangedDateTime": "2026-02-11T19:40:02Z",
    "isActive": true,
    "tags": [],
    "type": "Standard",
    "status": "Requested",
    "start": "2026-02-11T09:00:00+00:00",
    "end": "2026-02-11T10:00:00+00:00",
    "userId": "3a086ddc-1be7-45c4-a7c6-7297ede0e960",
    "loadTypeId": "e4fbeabd-a501-4f3b-bc11-7f034110e925",
    "dockId": "c9fbc7d2-f9c3-483c-84b4-1215682af6a3",
    "customFields": [
      {
        "name": "emailDispatcher",
        "type": "email",
        "label": "Dispatcher",
        "description": "Dispatcher's email address",
        "placeholder": "xpto@example.com",
        "dropDownValues": []
      }
    ],
    "notes": "",
    "orgId": "7e77fbe1-9517-44ce-b08b-5a18b478b79f",
    "statusTimeline": {
      "NoShow": null,
      "Arrived": null,
      "Cancelled": null,
      "Completed": null,
      "Requested": "2026-02-11T19:40:00.000Z",
      "Scheduled": null,
      "InProgress": null
    },
    "ccEmails": [],
    "createdBy": "867cef72-a49d-42f1-a605-f49c5fbc7ae4",
    "lastChangedBy": "867cef72-a49d-42f1-a605-f49c5fbc7ae4",
    "recurringParentId": null,
    "recurringPattern": null,
    "reschedules": null,
    "eta": null,
    "confirmationNumber": 135939,
    "muteNotifications": false,
    "isCheckedInByCarrier": false,
    "metadata": {
      "externalValidationFailed": false,
      "externalValidationErrorMessage": null
    },
    "refNumbers": [
      "AB21890128",
      "8210981"
    ],
    "units": null,
    "searchableCustomFields": "[]"
  },
  "sentAt": "2026-02-11T12:40:02.396-07:00"
}

AssetVisit

{
  "entity": "AssetVisit",
  "operation": "Create",
  "data": {
    "id": "90ba9c58-0e47-4d9c-9d1b-7e1474bc7e61",
    "createDateTime": "2026-02-11T19:54:56Z",
    "createdBy": "867cef72-a49d-42f1-a605-f49c5fbc7ae4",
    "lastChangedDateTime": "2026-02-11T19:54:56Z",
    "lastChangedBy": "867cef72-a49d-42f1-a605-f49c5fbc7ae4",
    "isActive": true,
    "tags": null,
    "orgId": "7e77fbe1-9517-44ce-b08b-5a18b478b79f",
    "warehouseId": "d4e4937e-5661-4599-9480-84e1d4af9d2c",
    "appointmentId": null,
    "companyId": "7baf6267-9af5-434b-a09b-54cdba2666e1",
    "phone": "+14809998888",
    "isPlanned": false,
    "companyHint": "Excel Transport",
    "checkInAcknowledged": false,
    "visitType": "LiveLoad",
    "driverNotes": null,
    "driverAppointmentIdentifier": null,
    "licensePlate": "XPT-1234",
    "dotNumber": "1234567"
  },
  "sentAt": "2026-02-11T12:54:56.278-07:00"
}

AssetContainer

{
  "entity": "AssetContainer",
  "operation": "Update",
  "data": {
    "id": "ee48b2bb-c27d-472f-a881-0dff36988494",
    "createDateTime": "2025-06-12T16:54:33Z",
    "createdBy": "f1e69f35-f01a-452e-9abf-e01a1ab1c9c5",
    "lastChangedDateTime": "2026-02-11T19:58:17Z",
    "lastChangedBy": "867cef72-a49d-42f1-a605-f49c5fbc7ae4",
    "isActive": true,
    "tags": null,
    "type": "Trailer",
    "code": "1234251",
    "assetVisitId": null,
    "orgId": "7e77fbe1-9517-44ce-b08b-5a18b478b79f",
    "warehouseId": "d4e4937e-5661-4599-9480-84e1d4af9d2c",
    "pickupAppointmentId": null,
    "dropAppointmentId": null,
    "notes": "Created by the yard view test tool",
    "state": null,
    "companyId": null
  },
  "sentAt": "2026-02-11T12:58:17.718-07:00"
}

note

Spot assignments are not reflected within the AssetContainer payload. Spot assignment data is stored separately — see Yard Operations for details. To track spot changes, register a webhook for the SpotAssignment entity instead.

Bol

{
  "entity": "Bol",
  "operation": "Update",
  "data": {
    "id": "92de5020-fc6d-443a-b417-f82238053642",
    "createDateTime": "2025-12-18T14:09:37Z",
    "createdBy": "46413dd9-fafc-4169-99e4-2cd39b52aa00",
    "lastChangedDateTime": "2026-02-11T20:09:40Z",
    "lastChangedBy": "46413dd9-fafc-4169-99e4-2cd39b52aa00",
    "isActive": true,
    "tags": null,
    "appointmentId": "f654feb5-1cd9-481c-8d8a-b53eb68b776e",
    "warehouseId": "c604ae67-6692-4351-a268-d35b03702055",
    "orgId": "53a44a4a-57fa-4bbb-9adc-a4ded39a8029",
    "signedDocId": "f83f5e1f-4b6b-48df-8c7a-842fb318880d",
    "originalDocId": "6bcb1d88-f9bf-493c-8fce-769d344ccfed"
  },
  "sentAt": "2026-02-11T13:09:40.088-07:00"
}

The following Delete example shows that the full entity data at the time of deletion is still included in the payload:

{
  "entity": "Bol",
  "operation": "Delete",
  "data": {
    "id": "afaa52ae-b6da-47e3-b878-d59a7d1528d3",
    "createDateTime": "2026-02-13T13:53:34Z",
    "createdBy": null,
    "lastChangedDateTime": "2026-02-13T13:53:34Z",
    "lastChangedBy": null,
    "isActive": true,
    "tags": null,
    "appointmentId": "6fb6f1a8-61e9-4f3d-8f0b-5a9a1ff7269c",
    "warehouseId": "746a7b37-9592-45db-8a58-656c7727603d",
    "orgId": "7e77fbe1-9517-44ce-b08b-5a18b478b79f",
    "signedDocId": null,
    "originalDocId": "2bca02c5-1686-422b-994e-5759b2c6370f"
  },
  "sentAt": "2026-02-13T06:53:59.160-07:00"
}

Supported Operations

Operation	Description
Create	A new entity record is created
Update	An existing entity record is modified
Delete	An entity record is deleted

Webhook Payload Structure

When a webhook fires, Opendock sends an HTTP POST request with a JSON payload to your registered endpoint. Every payload follows the same top-level structure:

{
  "entity": "<EntityName>",
  "operation": "Create | Update | Delete",
  "data": { ... },
  "sentAt": "2024-01-15T14:30:01.234Z"
}

Field	Type	Description
entity	string	The entity type that triggered the webhook (e.g., Appointment, Dock)
operation	string	The operation that occurred: Create, Update, or Delete
data	object	The full entity data at the time of the event — fields vary by entity type (see examples above)
sentAt	string (ISO 8601)	Timestamp when the webhook was dispatched

HTTP Request Details

Every webhook delivery follows this format:

Property	Value
Method	POST
Content-Type	application/json
Headers	Custom headers provided during registration (including authentication)
Timeout	8000ms (8 seconds)

Example Use Cases

1. Real-time Appointment Status Updates

Scenario: A system needs to stay synchronized with appointment statuses in Opendock. When a driver checks in an appointment, the external TMS should be notified immediately to update the appointment status.

Registration Details:

Parameter	Value
Entity	Appointment
Operation	Update
Target URL	https://api.customer-tms.com/webhooks/opendock/appointments

Headers:

{
  "Authorization": "Bearer sk_live_abc123xyz456",
  "X-Webhook-Source": "Opendock"
}

Sample Webhook Payload:

{
  "entity": "Appointment",
  "operation": "Update",
  "data": {
    "id": "0347e2b7-f9b4-4c1d-8774-bdbec96cc75b",
    "createDateTime": "2026-02-11T19:40:02Z",
    "lastChangedDateTime": "2026-02-11T19:41:42Z",
    "isActive": true,
    "tags": [],
    "type": "Standard",
    "status": "Arrived",
    "start": "2026-02-11T09:00:00+00:00",
    "end": "2026-02-11T10:00:00+00:00",
    "userId": "3a086ddc-1be7-45c4-a7c6-7297ede0e960",
    "loadTypeId": "e4fbeabd-a501-4f3b-bc11-7f034110e925",
    "dockId": "c9fbc7d2-f9c3-483c-84b4-1215682af6a3",
    "customFields": [
      {
        "name": "emailDispatcher",
        "type": "email",
        "label": "Dispatcher",
        "description": "Dispatcher's email address",
        "placeholder": "xpto@example.com",
        "dropDownValues": []
      }
    ],
    "notes": "",
    "orgId": "7e77fbe1-9517-44ce-b08b-5a18b478b79f",
    "statusTimeline": {
      "NoShow": null,
      "Arrived": "2026-02-11T19:41:00.000Z",
      "Cancelled": null,
      "Completed": null,
      "Requested": "2026-02-11T19:40:00.000Z",
      "Scheduled": "2026-02-11T19:40:00.000Z",
      "InProgress": null
    },
    "ccEmails": [],
    "createdBy": "867cef72-a49d-42f1-a605-f49c5fbc7ae4",
    "lastChangedBy": "867cef72-a49d-42f1-a605-f49c5fbc7ae4",
    "recurringParentId": null,
    "recurringPattern": null,
    "reschedules": null,
    "eta": null,
    "confirmationNumber": 135939,
    "muteNotifications": false,
    "isCheckedInByCarrier": false,
    "metadata": {
      "externalValidationFailed": false,
      "externalValidationErrorMessage": null
    },
    "refNumbers": [
      "AB21890128",
      "8210981"
    ],
    "units": null,
    "searchableCustomFields": "[]"
  },
  "sentAt": "2026-02-11T12:41:42.698-07:00"
}

Benefit: The TMS receives instant updates without polling the API every few minutes, reducing API load and improving data freshness.

2. Asset Visit Tracking

Scenario: A system needs to track container movements. They need real-time notifications whenever a container arrives or moves to a new spot in the yard.

Registration Details:

Two separate webhooks are registered:

Parameter	Webhook 1	Webhook 2
Entity	AssetVisit	AssetVisit
Operation	Create	Update
Target URL	https://your-system.com/api/v1/asset-visit-events	(same)

Headers:

{
  "X-API-Key": "pk_prod_9876543210",
  "X-Facility-Code": "WH-ATLANTA-01"
}

Sample Webhook Payload (Create — New Arrival):

{
  "entity": "AssetVisit",
  "operation": "Create",
  "data": {
    "id": "90ba9c58-0e47-4d9c-9d1b-7e1474bc7e61",
    "createDateTime": "2026-02-11T19:54:56Z",
    "createdBy": "867cef72-a49d-42f1-a605-f49c5fbc7ae4",
    "lastChangedDateTime": "2026-02-11T19:54:56Z",
    "lastChangedBy": "867cef72-a49d-42f1-a605-f49c5fbc7ae4",
    "isActive": true,
    "tags": null,
    "orgId": "7e77fbe1-9517-44ce-b08b-5a18b478b79f",
    "warehouseId": "d4e4937e-5661-4599-9480-84e1d4af9d2c",
    "appointmentId": null,
    "companyId": "7baf6267-9af5-434b-a09b-54cdba2666e1",
    "phone": "+14809998888",
    "isPlanned": false,
    "companyHint": "Excel Transport",
    "checkInAcknowledged": false,
    "visitType": "LiveLoad",
    "driverNotes": null,
    "driverAppointmentIdentifier": null,
    "licensePlate": "XPT-1234",
    "dotNumber": "1234567"
  },
  "sentAt": "2026-02-11T12:54:56.278-07:00"
}

Benefit: The system maintains accurate real-time tracking of container locations without complex polling logic.

Endpoint Implementation Guidelines

Your endpoint should follow this general pattern:

1. Validate headers — Verify authentication tokens and expected headers.
2. Return HTTP 200 or 204 immediately — Acknowledge receipt before heavy processing.

// Successful response (body is optional and not processed by Opendock)
HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "received"
}

Response Expectations

Aspect	Details
Expected Status Codes	200 OK or 204 No Content
Failure Logging	Any non-2xx response is logged as a delivery failure
Response Body	Not processed or stored by Opendock — can be empty or contain any content
Timeout	8000ms (8 seconds)

Best Practice

Acknowledge receipt quickly and process webhooks asynchronously. This pattern prevents your processing time from impacting webhook delivery reliability.

Important Limitations

Since this is an experimental feature, be aware of the following constraints:

No Dynamic Authentication

Only static or fixed authentication tokens are supported (e.g., Bearer tokens in headers). The following are not supported:

• OAuth 2.0 flows
• JWT refresh flows
• Dynamic token generation or rotation

No Automatic Retries

If a webhook delivery fails (e.g., your endpoint is down or returns a non-2xx response), the delivery will not be retried automatically. Your endpoint must be reliable and highly available to avoid missing events.

One Webhook Per Combination

Each registration is scoped to a single entity + operation + warehouse combination. To monitor multiple operations on the same entity, you need separate registrations.

Manual Management Only

Webhooks can only be registered, modified, or deactivated by contacting Opendock support. There is no self-service UI or API for webhook management at this time.