Webhook Events

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

The message body

Any messages sent by Spoke will have the following structure:

EventSchema = Object

Example

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

Properties

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.2b'	The Spoke 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.

EventType

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" | "stop.departed" | "stop.tracking_link_added" | "unassigned_stop.tracking_link_added" | "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. The data field is a Stop
• 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. The data field is a Stop
• 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. The data field is a Stop
• stop.departed: When the driver departs from a stop. This is triggered when the stop's departedAt timestamp is set, either by the driver app during normal delivery flow or by route completion for the final stop. The data field is a Stop. The stop's deliveryInfo.timeAtStopInfo object will include arrivedAt, departedAt, and isEstimated fields, which can be used to compute the time spent at each stop. When the team's plan does not support time at stop, timeAtStopInfo is null and timeAtStopInfoNullReason explains why
• stop.tracking_link_added: When the tracking link becomes available for a stop (e.g., when a stop is assigned to a plan or route, a stop is duplicated, or a driver adds a new stop). The data field contains a Stop.
• unassigned_stop.tracking_link_added: When the tracking link becomes available for an unassigned stop (e.g., when a stop is imported, or duplicated before being assigned). The data field contains an Unassigned Stop.
• test.send_event: Event sent when the user triggers a webhook test. The data field is a Test

note

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

note

Only a single tracking-link event is sent for each stop, either unassigned_stop.tracking_link_added or stop.tracking_link_added, depending on when the tracking link was generated.

note

Spoke 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.