Webhooks

Table of Contents

• Managing Webhook Subscriptions
• Payload
• Verifying Webhook Requests
• Retry Policy and Subscription Deactivation
• Actions
  • Order Actions
  • Damage Actions
• Testing Webhooks

Super Dispatch uses webhooks to notify your system when events happen on the Carrier TMS. When you subscribe to a webhook action, Super Dispatch sends a POST request with a JSON payload to your callback URL each time that event occurs.

Managing Webhook Subscriptions

List Available Webhooks

Retrieve all available webhook actions:

curl -X "GET" "https://carrier.superdispatch.com/v1/webhooks/" \
     -H 'Authorization: Bearer <access_token>'

Subscribe to a Webhook Action

Subscribe by providing a callback URL:

curl -X "POST" "https://carrier.superdispatch.com/v1/webhooks/<webhook_action>/subscriptions/" \
     -H 'Authorization: Bearer <access_token>' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "callback_url": "<callback_url>"
}'

The response confirms the subscription:

{
  "is_active": true,
  "action": "<webhook_action>",
  "verification_token": "a1f9c8e3b4d2f7e6...",
  "callback_url": "<callback_url>"
}

Save the verification_token — you will need it to verify incoming webhook requests.

Unsubscribe From a Webhook Action

curl -X "DELETE" "https://carrier.superdispatch.com/v1/webhooks/<webhook_action>/subscriptions/" \
     -H 'Authorization: Bearer <access_token>'

Payload

Every webhook request is a POST to your callback URL with a JSON body containing these fields:

Field	Type	Description
action	string	The webhook action (e.g., order.created).
guid	uuid	Unique identifier for this webhook message.
occurred_at	datetime	When the event occurred (ISO 8601).
data	object	Event-specific data (varies by action).

Example payload for order.created:

{
  "action": "order.created",
  "guid": "550e8400-e29b-41d4-a716-446655440000",
  "occurred_at": "2025-01-15T14:30:00.000000+0000",
  "data": {
    "id": 38093183,
    "status": "new"
  }
}

Verifying Webhook Requests

Every webhook request includes a X-Super-Dispatch-Verification-Token header. This token matches the verification_token returned when you subscribed. Use it to verify that incoming requests are from Super Dispatch and not from a third party.

Example verification in Python:

def handle_webhook(request):
    expected_token = "your_saved_verification_token"
    received_token = request.headers.get("X-Super-Dispatch-Verification-Token")

    if received_token != expected_token:
        return Response(status=403)

    # Process the webhook
    payload = request.json()
    ...

Retry Policy and Subscription Deactivation

Your endpoint must return a 2xx HTTP response within 3 seconds. Otherwise, the request is considered failed.

Failed requests are retried with exponential backoff:

Attempt	Delay before retry
1st retry	1 second
2nd retry	2 seconds
3rd retry	4 seconds

After the initial request plus 3 retries (4 total attempts), if all attempts fail, the subscription is automatically deactivated.

Automatic Deactivation

A subscription is deactivated when all webhook messages sent to it in the last 24 hours have failed. Once deactivated:

• No further webhook messages will be delivered for that action.
• No notification is sent to inform you of the deactivation.
• The subscription's is_active field becomes false.

caution

Automatic deactivation can be triggered by transient issues such as a brief server outage or slow response times exceeding the 3-second timeout. Monitor your webhook subscriptions to detect deactivation early.

Reactivating a Subscription

To reactivate a deactivated subscription, unsubscribe and subscribe again:

# 1. Unsubscribe
curl -X "DELETE" "https://carrier.superdispatch.com/v1/webhooks/<webhook_action>/subscriptions/" \
     -H 'Authorization: Bearer <access_token>'

# 2. Subscribe again
curl -X "POST" "https://carrier.superdispatch.com/v1/webhooks/<webhook_action>/subscriptions/" \
     -H 'Authorization: Bearer <access_token>' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "callback_url": "<callback_url>"
}'

Note that a new verification_token will be generated. Update your verification logic accordingly.

Actions

Order Actions

Action	Is sent when...	Payload
order.created	A new order is created	View
order.assigned	An order is assigned to a driver	View
order.updated	Order details are modified	View
order.picked_up	An order is picked up	View
order.delivered	An order is delivered	View
order.cancelled	An order is cancelled	View

Damage Actions

Action	Is sent when...	Payload
damage.created	A damage report is created	View
damage.deleted	A damage report is deleted	View

Testing Webhooks

We recommend using webhook.site during the implementation process to test the delivery and payload of webhook requests.