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 instantly notified 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
• Audit trail of all appointment activity

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. Each location can have webhooks for different notification types.

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 contains the complete appointment data in JSON format, rendered directly from the appointments view template. It includes all relevant appointment details such as:

{
  "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_name": "Dock 5"
  // Full appointment data...
}

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
appointment_arrived	A truck arrives for an appointment
appointment_started	Loading/unloading begins
appointment_completed	Loading/unloading is completed
appointment_drop_trailer_completed	Drop trailer operation is completed
appointment_left	A truck leaves after an appointment
appointment_cancelled	An appointment is cancelled
appointment_schedule_changed	An appointment's schedule has been modified
appointment_note_added	A note has been added to an 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	An appointment has been edited

Security

DataDocks sends webhooks through a secure proxy server to ensure reliable delivery and secure communication. 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

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. Implement your own retries — If your system requires guaranteed processing, implement your own retry logic
4. Always verify the token — Never skip token verification in production
5. Monitor failures — Set up alerts for webhook delivery failures

Troubleshooting

Location settings page has a webhooks section where you can see the webhook logs and test the webhook.

Issue	Possible Cause	Solution
Missing events	Webhook URL is unreachable	Check your server logs and firewall settings
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 endpoint URL where webhooks should be sent

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

Webhook Logs

DataDocks maintains logs of all webhook attempts, including the payload sent and any error messages received. These logs help with troubleshooting and auditing webhook deliveries. If you're experiencing issues with webhooks, please contact support and reference any specific appointment IDs involved or visit the location settings page to see the webhook logs.