What it does
- Named boundaries. Simple areas, areas with holes cut out of them, and multi-part shapes — two non-adjacent suburbs, or a zone split by a harbour, treated as one named boundary.
- Entry and exit detection against live driver and device positions, evaluated as positions arrive.
- Signed webhook delivery of every crossing to an endpoint you register.
- Shared shapes. A boundary defined here can also serve as a service area or a rate zone without being duplicated.
The common uses: tell a customer their driver is nearby, alert when a vehicle leaves the area it should be working in, confirm a driver was actually at a site before a stop can be completed, and measure time spent on a customer’s premises.
How it works
Detected as positions arrive
Crossings are evaluated against the live position stream as fixes come in, not by a job that sweeps every boundary on a timer. An entry event fires within moments of the crossing rather than at the top of the next minute. For an “arriving soon” notification, that difference is the whole feature — a message that lands after the driver has already knocked is worse than none.
Crossings, not presence
Detection remembers where each tracked subject already was. A driver who enters a boundary and stays inside for twenty minutes produces one entry event, not one per position fix. You are told about the transition, which is the thing that actually happened; a naive implementation that tested each position independently would flood you with hundreds of duplicate alerts for a single visit.
One shape, many uses
A boundary is a first-class, reusable shape rather than something private to one geofence. The same suburb outline can simultaneously be a geofence that fires alerts, a service area that determines which drivers are eligible, and a rate zone that prices deliveries into it. Define it once; link it from wherever you need it.
Two ways to change a shape, and the difference matters
If the boundary itself is wrong — a suburb was redistricted — you edit the shape, and every geofence, service area and rate zone linked to it moves together. If instead you want this particular geofence to cover a different area, editing it from the geofence creates a private copy and re-points only that geofence; everything else is untouched.
This is deliberate, and it is the protection that makes shared shapes safe. Without it, adjusting an alerting boundary could silently reprice a customer’s deliveries. A module edit never mutates a shared shape.
Definition here, reaction downstream
This module owns the boundary and the crossing. What happens next — send a text, call your system, block a stop completion — is yours, driven off the event. That keeps the boundary reusable across every reaction you might want, rather than tangling the shape up with one particular automation.
Permissions
| Permission | What it allows | Needed |
|---|---|---|
| geofences.read | Read geofence definitions and the boundaries they are linked to. | Required |
| geofences.write | Create, update and delete geofences, including forking a boundary for a single geofence. | Required to configure |
| polygons.read | Read the shared boundary library, and link an existing shape to a geofence. | Required |
| polygons.write | Create and edit shapes in the shared library. A propagating edit additionally requires write permission on every module currently linked to that shape. | Optional |
| tracking.read | Read the positions that crossings are detected from. | Recommended |
| subscriptions.read | Read the webhook subscriptions that crossing events are delivered to. | Required to receive |
| subscriptions.write | Register a webhook endpoint and rotate its signing secret. | Required to receive |
| drivers.read | Resolve a crossing back to the driver who caused it. | Recommended |
The boundary-library permissions only take effect alongside at least one of geofences, service areas or rates. The shared shape library exists to serve those three; it is not granted on its own.
API reference
Two contracts: the geofences themselves, and the shared shape library their boundaries come from.
| Service | What it covers | Reference | Contract |
|---|---|---|---|
| geofences-api | Geofence definitions — create, read, update, delete. | OpenAPI description | openapi.json |
| polygons-api | The shared boundary library. A PUT here propagates to everything linked. | OpenAPI description | openapi.json |
Each openapi.json is the generated OpenAPI 3.1 contract, served by the service itself — it is never hand-edited, so it cannot drift from the running API. The OpenAPI description link opens the same contract as a browsable reference. Both resolve to the environment these docs are served from, so a page read on the test site links to the test contract.
Events
This module is an event producer — the events are the product.
| Event | Raised when | Tells you |
|---|---|---|
| geofence.entered | A tracked driver or device crosses into the boundary. | The geofence and its name, the boundary it used, the device and driver, the coordinates of the crossing, and the time the position was taken. |
| geofence.exited | A tracked driver or device crosses out of the boundary. | The same detail as entry. |
Time-inside-a-boundary (dwell) triggers are designed but not yet published. Today you can derive dwell yourself from the gap between an entry and its matching exit, both of which carry the position timestamp.
Delivery
Crossing events reach you through the platform’s event pipeline: you register an endpoint, the platform mints a signing secret for it once, and every delivery is signed so you can verify it genuinely came from Mesh. Failed deliveries are retried; permanently undeliverable ones are set aside rather than dropped silently. You can rotate the signing secret at any time.
Related events
| Event | Raised when | Tells you |
|---|---|---|
| stop.arrived | The driver arrives at a stop. | Often paired with a geofence entry — one is the operational record, the other the geographic fact. |
| stop.completed | A stop reaches its terminal completed state. | Where completion is gated on being inside a boundary, this is the confirmed outcome. |
The envelope these arrive in, the delivery and retry guarantees, and every other event type are in Events & webhooks — or jump straight to the event catalog.