Common message structure

This document describes the common message structure all the Circuit's webhook events share.

The message body

Any messages sent by Circuit will have the following structure:

Ƭ EventSchema: Object

Example

{
  "type": "stop.allocated",
  "version": "v0.1b",
  "created": 1669153051588,
  "data": {
    ..."data based on the event type"
  }
}

Type declaration

Name	Type	Description
`type`	`EventType`	The event type being sent. This has the format `<resource>.<event>`. `Example` When a `stop` is allocated to a driver the `type` will be `stop.allocated`.
`version`	`'v0.1b'`	The Circuit API version for this event. This specifies how the data format will be.
`created`	`number`	The epoch, in milliseconds, of when the event occurred.
`data`	`Object`	The event data. This will vary depending on the event body.

The EventType, which defines what kind of data each event will have as well as what resource type the event happened upon.

Ƭ EventType: "stop.allocated" | "stop.out_for_delivery" | "stop.attempted_delivery" | "test.send_event"

Description

stop.allocated: When a stop is allocated to a driver. This is triggered when a dispatcher sends the routes to the drivers.
stop.out_for_delivery: When a package for a stop starts making its way to the recipient. This is triggered when the driver start their route.
stop.attempted_delivery: When the delivery state of the package for a stop is changed. This is triggered when the driver attempts a delivery, if successful or not.
test.send_event: Event sent when the user triggers a webhook test.

note

For the stop.allocated and stop.out_for_delivery types there will be one independent event sent per each stop.

note

Circuit will not send more than one event per request, so only the data related to the type field will ever be present in a request.