Stage - Event API

Event API

Create Subscriptions

Create new event subscriptions.

📝 Important Notes

  • Creates a webhook subscription for specified event types.
  • The response will be empty but includes three important headers.
  • The Api-Key header value should be stored by the caller and used to authenticate all incoming events from Central Dispatch. The value will be contained in the Api-Token header in all events delivered as part of this subscription.
  • The response will contain a Location header that contains the fully qualified URL of the newly created resource. The final segment of the URL will be the ID of the resource.
  • The response will include an ETag header, which should be used for the If-Match header in subsequent updates.
post
https://event-api.centraldispatch.com/subscriptions

Headers

Content-Typestringrequired

The major version of the API to make a request against. This is a custom MIME type that contains vnd.coxauto.v[#]+. For example, to request a resource from version 1.x.x of an API, the Content-Type header should be set to application/vnd.coxauto.v1+json.

Example:application/vnd.coxauto.v1+json

Body

application/json

SubscriptionRequest

SubscriptionRequest

Details of a subscription.

callbackUrlstringrequired

A valid URL that you own, which will be used to receive event notifications from the Central Dispatch Event service.

Example:https://abc-trcking.net/webhook

subscriptionRulesobjectrequired

Details of subscription rules.

Show Child Parameters

Response

Created. Successful request.

post/subscriptions

Body

{ "callbackUrl": "https://abc-trcking.net/webhook", "subscriptionRules": { "marketplaces": [ "10000" ], "eventTypes": [ "DispatchCreated", "DispatchUpdated", "DispatchAccepted" ] } }
 

Get Subscription

Get a subscription by ID.

📝 Important Notes

  • Returns the subscription details including webhook URL and subscription rules.
  • The response will include an ETag header, which should be used for the If-Match header in subsequent updates.
get
https://event-api.centraldispatch.com/subscriptions/id/{subscriptionId}

Path Parameters

subscriptionIdstring(uuid)required

The ID of the subscription.

Example:50b2863f-c75e-45cb-8d50-b5a975d67865

Headers

Acceptstringrequired

The major version of the API to make a request against. This is a custom MIME type that contains vnd.coxauto.v[#]+. For example, to request a resource from version 1.x.x of an API, the Accept header should be set to application/vnd.coxauto.v1+json.

Example:application/vnd.coxauto.v1+json

Response

application/json

OK. Successful request.

SubscriptionResponse

Details of a subscription.

hrefstring

The fully qualified URL of the subscription.

Example:https://event-api.centraldispatch.com/subscriptions/id/50b2863f-c75e-45cb-8d50-b5a975d67865

subscriptionIdstring(uuid)

The ID of the subscription.

Example:50b2863f-c75e-45cb-8d50-b5a975d67865

callbackUrlstring

A valid URL that you own, which will be used to receive event notifications from the Central Dispatch Event service.

Example:https://abc-trcking.net/webhook

isEnabledboolean

Indicates whether the subscription is currently active.

Example:true

subscriptionRulesobject

Details of subscription rules.

Show Child Parameters
get/subscriptions/id/{subscriptionId}
 
application/json

Update Subscription

Update a subscription.

📝 Important Notes

  • Requires the full subscription payload for updates.
  • Must include all existing event types plus any new ones.
  • The If-Match header is required and its value can be found in the ETag response header of the resource’s GET by ID endpoint.
put
https://event-api.centraldispatch.com/subscriptions/id/{subscriptionId}

Path Parameters

subscriptionIdstring(uuid)required

The ID of the subscription.

Example:50b2863f-c75e-45cb-8d50-b5a975d67865

Headers

If-Matchintegerrequired

This is a required field to ensure the update is being completed on an item that has not changed since it was last read. The value of this field will be the value of the ETag header that was received on the preceding get call.

Example:8675309

Content-Typestringrequired

The major version of the API to make a request against. This is a custom MIME type that contains vnd.coxauto.v[#]+. For example, to request a resource from version 1.x.x of an API, the Content-Type header should be set to application/vnd.coxauto.v1+json.

Example:application/vnd.coxauto.v1+json

Body

application/json

UpdateSubscriptionRequest

UpdateSubscriptionRequest

Details of update subscription request.

callbackUrlstringrequired

A valid URL that you own, which will be used to receive event notifications from the Central Dispatch Event service.

Example:https://abc-trcking.net/webhook

subscriptionRulesobjectrequired

Details of subscription rules.

Show Child Parameters
isEnabledboolean

Indicates whether the subscription is currently active.

Default:false

Example:true

Response

No Content. Successful request.

put/subscriptions/id/{subscriptionId}

Body

{ "callbackUrl": "https://abc-trcking.net/webhook", "subscriptionRules": { "marketplaces": [ "10000" ], "eventTypes": [ "DispatchCreated", "DispatchUpdated", "DispatchAccepted", "DispatchVehiclePickedup", "DispatchVehicleDelivered" ] }, "isEnabled": true }
 

Renew Subscription

Renew your subscription API key.

📝 Important Notes

  • Use this endpoint if your API key was lost or compromised.
  • The new Api-Key will be returned in the response headers.
  • The old API key will be immediately invalidated.
  • All future events will use the new API key for authentication.
  • The If-Match header is required and its value can be found in the ETag response header of the resource’s GET by ID endpoint.
post
https://event-api.centraldispatch.com/subscriptions/id/{subscriptionId}/renew

Path Parameters

subscriptionIdstring(uuid)required

The ID of the subscription.

Example:50b2863f-c75e-45cb-8d50-b5a975d67865

Headers

If-Matchintegerrequired

This is a required field to ensure the update is being completed on an item that has not changed since it was last read. The value of this field will be the value of the ETag header that was received on the preceding get call.

Example:8675309

Content-Typestringrequired

The major version of the API to make a request against. This is a custom MIME type that contains vnd.coxauto.v[#]+. For example, to request a resource from version 1.x.x of an API, the Content-Type header should be set to application/vnd.coxauto.v1+json.

Example:application/vnd.coxauto.v1+json

Response

No Content. Successful request.

post/subscriptions/id/{subscriptionId}/renew
 

Reactivate Subscription

Re-enables a subscription that has been deactivated. Sets the subscription status to active so that event notifications resume delivery to the registered callback URL. The existing API token is preserved — the partner does not need to update their cached token after reactivation.

📝 Important Notes

  • The If-Match header is required and its value can be found in the ETag response header of the resource’s GET by ID endpoint.
post
https://event-api.centraldispatch.com/subscriptions/id/{subscriptionId}/reactivate

Path Parameters

subscriptionIdstring(uuid)required

The ID of the subscription.

Example:50b2863f-c75e-45cb-8d50-b5a975d67865

Headers

If-Matchintegerrequired

This is a required field to ensure the update is being completed on an item that has not changed since it was last read. The value of this field will be the value of the ETag header that was received on the preceding get call.

Example:8675309

Content-Typestringrequired

The major version of the API to make a request against. This is a custom MIME type that contains vnd.coxauto.v[#]+. For example, to request a resource from version 1.x.x of an API, the Content-Type header should be set to application/vnd.coxauto.v1+json.

Example:application/vnd.coxauto.v1+json

Response

No Content. Successful request.

post/subscriptions/id/{subscriptionId}/reactivate