Place busyness webhooks are a paid extension. Contact your MotionTools account manager to have them enabled. If you don’t know what place busyness webhooks are, learn more about them here.
Overview
Set Up a Webhook Subscription
Admin users can create webhook subscriptions in the MotionTools Dashboard.
Go to Settings → Webhooks and click Create webhook.
Activate the Webhook.
Give the Webhook a name and enter the endpoint URL where you want to receive webhooks.
Then, set the customer_id filter by clicking on Add rule and entering 'customer_id' as the field name and the ID of the customer whose places you want to monitor as the value.
The customer_id filter is required. You cannot create a busyness webhook subscription without it. This ensures webhooks are scoped to the relevant places only.
Scroll down and enable the event busyness.place_changed in the webhook group Busyness Signals.
Scroll down to the end of the page and hit Save.
Test the Webhook Subscription
Once you've created a subscription, it's worth confirming end-to-end that your endpoint receives a well-formed webhook before wiring it into your production systems.
Because busyness webhooks are driven by real workforce demand on a recurring schedule (rather than a button you can press on demand), testing them takes a deliberate setup. This guide walks you through producing a real busyness change and verifying the delivery without assistance from MotionTools.
The single most important rule: create the place and its first booking before you create the webhook subscription. Eligible places are cached, so a place that is created or changed after the subscription may not be picked up for up to a few hours. Following the order below avoids this entirely.
Before you start
The busyness extension is enabled for your tenant (contact your account manager if you are unsure).
You have admin access to the MotionTools Dashboard.
You have a driver account and the driver app available for dispatching test tours.
You have somewhere to receive the webhook. For a quick test, a free inspection endpoint such as webhook.site works well; open it and copy the unique URL it gives you. For a more realistic test, point it at a staging endpoint in your own system.
Step 1: Prepare an eligible Place
A place only receives webhooks if it is active (not archived), recently active (at least one booking in the last 7 days), and belongs to the customer you will filter on. Set this up first:
Create (or choose) a customer in the Dashboard, and note its
customer_id. You will need it for the subscription.Create a place for that customer and set its
external_idat the same time.Create a booking that uses this place as its pickup.
Dispatch and complete one tour for that booking: go online as a driver, dispatch the booking into a tour, then start and finish it. This registers the place as recently active.
Set the external_id when the place is first created, as part of the booking. If a place is later re-created or "forked" (for example, MotionTools archives the old place and creates a new one when its name changes), the external reference can break and external_id will arrive as null. The most reliable approach is to create the place together with the booking so it carries its external ID from the start.
After this first activity, allow some time (up to a couple of hours) for the place to be recognized as an eligible, cached place before you continue.
Step 2: Create the Webhook Subscription
Now create the subscription as described in Set Up a Webhook Subscription above:
Endpoint URL: the receiver URL for the test, as explained above
customer_idfilter: the customer from Step 1.
No webhook arrives on the first evaluation. The first time your subscription is evaluated, MotionTools records the current busyness as a silent baseline. Your first webhook is delivered on the next evaluation where the stepped busyness value actually changes. A quiet first cycle is expected, not a failure.
Step 3: Trigger a Busyness Change
Busyness is the backlog ratio: open tours relative to active driver capacity in the service area. To move it across a 10-point step boundary, increase demand while keeping driver capacity low:
Duplicate the booking from Step 1 and dispatch it two or more times to build up open tours.
Keep few or no drivers online. With no driver (or only one) online against this demand, the backlog ratio rises above
0.Confirm the backlog ratio has moved in the Analytics Split View. Remember that a webhook is only sent when the value crosses into a new 10-point step (for example
0→10), not for every change within a step.
Step 4: Wait for the Next Evaluation Cycle
Busyness is re-evaluated on your tenant's configured schedule; by default, every 10 minutes (minimum 5). Wait at least one full cycle after triggering the change.
Step 5: Verify the Delivery
Check your receiver. You should see one busyness.place_changed delivery per eligible place, with:
place_idandservice_area_idmatching your test place and its service areacustomer_idmatching your subscription filterexternal_idmatching the value you set in Step 1 (notnull)busynessfloored to the nearest 10a
changed_attimestamp
If the place belongs to more than one service area, expect one webhook per area whose step changed.
Troubleshooting
Symptom | Likely cause & fix |
No webhook arrives at all | The place may not be eligible. Confirm it is active (not archived), had a booking in the last 7 days, and belongs to the subscription's |
No webhook, but everything looks eligible | If you created the place or booking after the subscription, eligibility caching can delay pickup by up to a few hours. Re-create the place and booking first, then the subscription (see the tip at the top). |
| The place was likely re-created or forked after the external ID was set, breaking the reference. Ensure the place is created with its external ID as part of the booking. |
Backlog ratio moved but no webhook | Expected if the value stayed within the same 10-point step, or if this was the first (baseline) evaluation for the subscription. |
Backlog ratio stays at | There is not enough open demand relative to online drivers. Dispatch more bookings and/or reduce the number of online drivers. |