Webhooks

Foxtrot uses Webhooks to notify your service when certain events occur within Foxtrot.

Each Webhook consists of a URL, a list of events, and a list of DCs. Whenever an event occurs in one of the DCs, a message will be posted to the Webhook URL.

You can create, read, update, and delete Webhooks using the Webhooks API methods.

Webhook Delivery

Webhooks notifications will be delivered to your Webhook URL as an HTTP POST in JSON format (with the header Content-Type: ‘application/json’ set):

{
  "event": "ROUTE_CREATED",  // The event the triggered the webhook
  "hook_timestamp_millis": 1572557276345,  // When the webhook event occurred
  "dc_id": "1"  // Which DC this event occurred in
  "route_id": "2"  // Which Route this event occurred in
}

The exact fields included in the body will vary depending on the type of event. See WebhookEventType for a full description of which data will be sent with which event.

Your Webhook processor should respond to the Webhook event with a 200 OK response. If you do not respond with 200 OK, Foxtrot will attempt to redeliver the Webhook event at a later time. However, if your service does not respond with a 200 OK response within several hours, Foxtrot will eventually drop that Webhook event.

If your Webhook continuously fails to respond to events for more than a day, Foxtrot may disable that Webhook and it’ll have to be enabled manually.

Models

Webhook

{
  "id": "the-webhook-identifier",
  "webhook_url": "https://example.com/webhook",
  "enabled": true,
  "dc_ids": ["1", "2", "3"],
  "events": ["ROUTE_CREATED", "ROUTE_STARTED"]
}

Property	Type	Nullable	Description
id	string	false	The id of the Webhook.
url	string	false	The name of the route.
dc_ids	Array[string]	false	An array of DC ids for which this Webhook will receive events.
events	Array[WebhookEventType]	false	An array of Event Types for which this Webhook will receive notifications.

WebhookEventType

An enumeration of possible webhook event types.

Method	Description	Data Sent
ROUTE_CREATED	Triggered when a route is created.	hook_timestamp_millis, event, dc_id, route_id
ROUTE_STARTED	Triggered when a driver clicks on Route Start or the start route API is called.	hook_timestamp_millis, event, dc_id, route_id
ROUTE_ETAS_CHANGED	Triggered when a route’s ETAs changed, after an optimization or ETA refresh if any of the route ETAs change.	hook_timestamp_millis, event, dc_id, route_id
WAYPOINT_STATUS_CHANGED	Triggered when a waypoint’s delivery gets a delivery attempt.	hook_timestamp_millis, event, dc_id, route_id, waypoint_id
CUSTOMER_LOCATION_CHANGED	Triggered when a customer’s location changes.	hook_timestamp_millis, event, dc_id, customer_id