Real-time Updates with Webhooks

Overview

Webhooks allow your applications to receive real-time notifications when events occur in DataDocks. Rather than polling the API for changes, your application can be notified asynchronously when appointments are created, updated, or change status.

When to Use Webhooks

• Real-time inventory updates when shipments arrive
• Automatic notifications to carriers when appointments are approved
• Custom workflow triggers when appointments change status
• Synchronization with your ERP, WMS, or TMS in real-time
• Integration activity tracking alongside periodic API reconciliation; webhooks are not a complete audit trail

How Webhooks Work

1. Select which events you want to receive notifications for and create a support ticket with the URL you want to receive the webhooks
2. When those events occur, DataDocks sends an HTTP POST request to your URL
3. Your server processes the event and responds with a 200 OK status

Webhook Implementation

DataDocks webhooks are configured at the location level, with one destination per notification type. Support can help enable the events you need and check your location's notification settings.

Authentication

Each webhook request includes the following headers:

Header	Description
x-datadocks-webhooks-token	Authentication token specific to the location
x-datadocks-host	The host identifier for the location (e.g., subdomain.datadocks.com)
content-type	Always set to application/json

Webhook Payload

The webhook payload uses the Appointments API response format. The following example shows selected fields:

{
  "id": 123,
  "appointment_number": 456,
  "state": "arrived",
  "carrier_name": "Express Logistics",
  "scheduled_at": "2023-10-15T14:00:00Z",
  "arrived_at": "2023-10-15T14:22:17Z",
  "dock": "Dock 5",
  "yard": null
}

The full payload includes appointment details, packing lists, notes, and available documents. See the linked response schema for field names and descriptions.

The payload does not identify the notification type. Use a different endpoint path for each type if you need to distinguish them. Payloads can include changes made after the original event, and requests may arrive out of order.

Available Notification Types

Webhooks can be configured for various notification types related to appointments:

Notification Type	Description
unscheduled_appointment_created	An unscheduled appointment is created
appointment_pending	An appointment is pending approval
appointment_approved	An appointment is approved, including automatic approval
appointment_arrived	A truck arrives for an appointment
appointment_started	Loading/unloading begins
appointment_completed	Loading/unloading is completed
appointment_drop_trailer_completed	A drop trailer appointment is completed
appointment_left	A truck leaves after an appointment
appointment_cancelled	An appointment is cancelled
appointment_schedule_changed	An appointment's scheduled date or time changes
appointment_note_added	A note is added to an existing appointment
appointment_delayed	An appointment has been marked as delayed
appointment_no_show	An appointment has been marked as no-show
appointment_late	An appointment has been marked as late
appointment_edit	Appointment details change without a separate status or schedule notification
appointment_document_added	A document is added to an existing appointment
appointment_booked_externally	An appointment is created through the Booking Portal

appointment_edit does not cover every change. Subscribe to the status and schedule events you need as well. When an update changes both status and scheduled time, the status notification takes precedence. A duration-only change does not trigger appointment_schedule_changed.

Security

Production webhook URLs must use HTTPS. Authentication is handled via the X-DataDocks-Webhooks-Token header, which contains a token specific to your location.

Verifying Webhook Authenticity

To verify that a webhook request is coming from DataDocks:

1. Store your location's webhooks token securely in your application
2. When receiving a webhook, compare the token in the X-DataDocks-Webhooks-Token header with your stored token
3. Only process the webhook if the tokens match

This is a shared-token check, not a payload signature. Keep the token out of logs.

Best Practices

1. Respond quickly — Webhook requests should be acknowledged with a 200 status code as quickly as possible
2. Process asynchronously — Queue the webhook for background processing if it requires complex operations
3. Retry processing and reconcile — Retry failures after durably receiving a payload, and use periodic API reconciliation to recover missed requests. Receiver-side retries cannot recover requests that never arrived
4. Always verify the token — Never skip token verification in production
5. Monitor failures — Monitor your receiver and processing queue; DataDocks logs do not capture HTTP error responses
6. Handle duplicate requests — Make processing safe to repeat

Timeouts and Delivery Behavior

Verify and store the payload before acknowledging it. Connection attempts time out after five seconds, and requests after ten seconds. Failed connections and HTTP error responses do not trigger automatic redelivery, so use API reconciliation to recover missed updates. Duplicate requests are possible.

Troubleshooting

The location settings page has a webhooks section where you can see configured endpoints and delivery logs.

Issue	Possible Cause	Solution
Missing events	Unreachable URL or missing event configuration	Check your endpoint and ask support to verify the event configuration
Invalid token	Token mismatch or configuration issue	Verify your webhook token is correct
Server errors	Your webhook endpoint is failing	Check your server logs for exceptions

Setting Up Webhooks

To configure webhooks for your DataDocks location, please contact our support team with the following information:

1. The location(s) for which you want to enable webhooks
2. The notification types you're interested in receiving
3. The HTTPS endpoint URL for each notification type (only one destination per type per location)

Our team will set up the appropriate webhook configuration and provide you with your location's webhook token.

Webhook Logs

Webhook logs in location settings show sent payloads and connection errors. They do not include your endpoint's response or confirm successful processing, so check your own server logs too. If an expected delivery is missing, contact support with the appointment ID, notification type, and approximate time.