Process a complete route update as a validated snapshot and protect every derived field from older events. A separate ETA or status update received later may concern an earlier state than the route snapshot. Without version checks, a delivery stop may revert from delivered to on the way, or an old route may appear current again.
A route webhook contains relationships
A route is more than a list of separate stops. Vehicle, sequence, planned date and stop identities together form the plan. First check that the snapshot belongs to the correct workspace, route and date, and that every record is valid. Only then project the relevant fields onto local delivery stops or the ERP.
A complete snapshot must not automatically treat missing stops as deleted. Determine whether the provider actually sent a complete authoritative route and whether the local route is still the same version. Deletion or unlinking is safe only when the received route demonstrably represents the current route.
Use a clock for each field
One general ‘last updated’ time is too broad. Status, ETA, vehicle and trip sequence may come from different events. For each relevant field, retain which provider event or version was last applied. A newer ETA may change the current arrival estimate without restoring an older status; a delivered status must not disappear because an outdated route snapshot arrives later.
| Field | Likely source | Protect against |
|---|---|---|
| Status | Stop or order event | Older route projection |
| ETA | Live route event | Outdated estimate |
| Vehicle | Complete route | Snapshot of the previous plan |
| Sequence | Complete route | Partial update without context |
This projection can form part of a configurable flow in Connect.
Fictional example: delivered is not reversed
Fictional example: route R-18 is refreshed at 15:10; stop 7 is assigned vehicle Bus 2 and position 4. At 15:42, a stop event reports that order 9087 has been delivered. Due to network delay, a route snapshot arrives at 15:50 that was created at 15:30 and shows the stop as on the way.
The integration still uses the snapshot for fields for which it is recent enough, but compares the status clock. ‘Delivered’ from 15:42 remains. The older snapshot does not reactivate the stop. If an entirely new route from 16:00 demonstrably moved the stop to another vehicle, the vehicle and sequence could change according to their own versions. This fictional example explains why one record timestamp is insufficient.
Route projection checklist
- Validate workspace, route ID, date and provider signature before processing.
- Determine explicitly whether the payload is complete or partial.
- Use exact stop and order identities; do not match on address alone.
- Retain a version or event time for each changing field.
- Remove a local route association only if the snapshot is authoritative and current.
- Make skipped older values visible in the technical audit trail.
- Deliberately test events out of sequence.
In Desk the employee needs to see the current delivery state, not every internal projection decision. During investigation, it must still be possible to trace which source and version determined the field. More about operational relationships between systems is covered under custom software for processes.
Run a chaos test using the same series of events in different orders. Start with a route snapshot, then send an ETA, a delivered event and finally the old snapshot again. Repeat the test with the old snapshot before the delivered event. The final visible state must be the same in both cases. Also check that a new vehicle can be applied without reversing the final delivery status. This demonstrates that the projection relies on meaningful versions rather than coincidental test-server timing.
Finally, separate operational corrections from source corrections. An employee may see locally that a stop is incorrect, but a local overwrite that disappears at the next route webhook creates false confidence. Determine where each field should be corrected: in route planning, in the online store or through a controlled service action. For a locally read-only field, show a link or instruction to the correct source so the team does not use a temporary workaround as a permanent solution.
For every manual correction, record which source needs to be read again afterwards. Otherwise the screen is temporarily correct, but the old provider state returns with the next event.
Want to make route webhooks withstand duplicate and delayed events? Discuss your status and version clocks with Yindle.