Stage - Event API

Event API

Search Events

Search for published events.

get
https://event-api.centraldispatch.com/integrator-events

Query Parameters

gt(createdOn,<startDateTime>)string

Search for events with created date greater than value, in UTC/ISO 8601 format.

Example:gt(createdOn,2024-01-19)

lt(createdOn,<endDateTime>)string

Search for events with created date less than value, in UTC/ISO 8601 format.

Example:lt(createdOn,2024-02-13)

eq(subscriptionId,<subscriptionId>)string

Search for events with subscription ID equal to value (GUID).

Example:eq(subscriptionId,50b2863f-c75e-45cb-8d50-b5a975d67865)

eq(eventId,<eventId>)string

Search for events with event ID equal to value (GUID).

Example:eq(eventId,eec2b82e-29b1-47c3-a391-6da6cce37d7d)

eq(publishStatus,<publishStatus>)string

Search for events with publish status equal to value. Allowed values: SUCCESS, FAILED.

Example:eq(publishStatus,SUCCESS)

eq(eventType,<eventType>)string

Search for events with event type equal to value. Use the Get Event Types endpoint to retrieve valid values.

Example:eq(eventType,DispatchCreated)

limit(startingPoint,numberOfResults)string

The maximum number of items to be returned in the response.

  • startingPoint is 1-based integer, default 1.
  • numberOfResults is an integer, default 500, maximum 500.

Example:limit(1,10)

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.

SearchIntegratorEventCollection

Details of search event.

hrefstring

The URL used to query the current collection of the resource.

Example:https://event-api.centraldispatch.com/integrator-events?limit(5,1)

previousstring | null

The URL to the previous page of the collection, if available.

Example:https://event-api.centraldispatch.com/integrator-events?limit(4,1)

firststring | null

The URL to the first page of the collection.

Example:https://event-api.centraldispatch.com/integrator-events?limit(1,1)

nextstring | null

The URL to the next page of the collection, if available.

Example:https://event-api.centraldispatch.com/integrator-events?limit(6,1)

countinteger(int32)

The total count of resources in the collection.

Example:23

limitinteger(int32)

The maximum number of items to be returned in the response.

Example:1

itemsarray[object]

Details of an event.

Show Child Parameters
get/integrator-events
 
application/json

Subscription

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 }