Search
K
Event API

Event API

1.0.0OAS 3.0

Central Dispatch’s Event API allows customers to receive event notifications. It offers a comprehensive list of events along with detailed descriptions, enabling users to subscribe to events of interest. Additionally, the API provides functionality to search and retrieve historical customer events.
🔑 Scope: event_api

📝 Important Notes

  • Event Notification does not guarantee order of event delivery, nor does it guarantee a single instance of event delivery. The end partner should support these eventualities. The eventId key in the event payload can be used to identify duplicate event deliveries.
  • The subscription response returns an Api-Token header that should be stored by the partner. This token will be sent with every event notification, and the partner should compare the Api-Token sent with each event against their own cached version to validate event authenticity. This is the only authentication that should be implemented for this endpoint.
  • Events and status of the events are presisted. If an eventing user is unable to receive events for some time, they can work with the Search Events endpoint.
  • The customer must provide an endpoint that CD event notification service can call to push the message.
  • The body of the events delivered to the customer’s webhook (supplied through subscription) will vary based on event type that is being delivered.
API Base URL
  • Server 1:https://event-api.centraldispatch.com

    Production server

Security
Bearer (http)

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer 123

Additional Information
Contact (datasyndicationsupport@centraldispatch.com)

Get Event Types

Get a collection of all events currently offered.
Returns a list of event types and descriptions, enabling users to create subscriptions for events of interest.

get
https://event-api.centraldispatch.com/event-types

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.

EventTypeCollection

Details of the event types.

hrefstringrequired

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

Example:https://event-api.centraldispatch.com/event-types

countinteger(int32)required

The total count of resources in the collection.

Example:1

itemsarray[object]required

Details of an event type.

Show Child Parameters
get/event-types
 
application/json

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

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