Place Busyness Webhooks are a paid extension. Contact your MotionTools account manager to have them enabled.
Overview
What is Busyness?
Busyness reflects how much demand pressure the workforce is currently under. When busyness is high, drivers are stretched and may not be able to fulfill new orders without delays. You can monitor busyness live in the Analytics Split View.
How Busyness is calculated
MotionTools calculates busyness using the backlog ratio, a measure of open tours relative to busy drivers in a service area. It is reported as a number between 0 and 100, in steps of 10:
A backlog ratio is floored to the nearest 10: for example, 12% is reported as
10, and 29% is reported as20Any backlog ratio of 100% or higher is capped at
100A webhook is only sent when the step value changes: if the backlog ratio moves but stays within the same 10-point bucket, no webhook is sent
Backlog ratio is evaluated per service area on a configurable schedule. You can verify the current backlog ratio for a service area in the Analytics Split View.
What are Place Busyness Webhooks?
Place busyness webhooks notify your system whenever the busyness level of the workforce changes for a specific place (e.g. a specific store). This lets you take automated throttling actions, such as temporarily offlining a store or reducing its delivery radius, when the operator in a service area is under high demand pressure.
Unlike standard event-driven webhooks, busyness webhooks are evaluated on a recurring schedule and only delivered when the busyness level of a service area crosses a meaningful threshold. Your system only gets notified when something actually changes.
Webhook Payload
Each webhook covers a single place and is delivered under the busyness.place_changed event, in the Busyness Signals webhook group (busyness.*).
Example payload:
{
"id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
"timestamp": "2020-11-09T10:19:07Z",
"resource_type": "busyness",
"event": "place_changed",
"data": {
"place_id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
"service_area_id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
"customer_id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
"external_id": "string",
"busyness": 10,
"changed_at": "2020-11-09T10:19:07Z"
}
}Field | Description |
| Internal MotionTools ID of the place |
| ID of the service area the busyness change is attributed to |
| ID of the customer the place belongs to |
| Your external reference ID for the place |
| Current stepped busyness value (0–100 in steps of 10) |
| Timestamp of when the step changed. Use this to discard stale deliveries in case of retried reordering. |
If a place belongs to more than one service area, you receive one separate webhook per service area. Each webhook carries the service_area_id of the area whose busyness changed.
Which Places receive Webhooks
A place must meet all of the following criteria to be eligible:
Active: not archived
Recently active: at least one booking in the last 7 days
Matching customer: belongs to the
customer_idset on the webhook subscription
Up to 5,000 places are considered per subscription. If more eligible places exist, the oldest places by creation date are prioritized and newer ones are excluded. An alert is sent to your configured notification channel if this limit is reached.
Evaluation Frequency
Busyness is re-evaluated for all relevant service areas on a schedule configured globally for your tenant. The default is every 10 minutes, with a minimum of 5 minutes. Contact your MotionTools account manager or support team to adjust the evaluation frequency.
Webhooks are only sent when the stepped busyness value changes, not on every evaluation cycle.
Set up and test a Webhook subscription
Please continue with the Set up and test place busyness webhooks article for more details.