--- title: "External Status Update From A Fleet Application" method: POST path: "/v1/webhook/fleet-status-update" tags: ["Use case / Fleet dispatch", "Webhooks / Inbound"] --- # External Status Update From A Fleet Application `POST /v1/webhook/fleet-status-update` Webhook for updating the status, ETA, and data of stops from an external fleet application. Note that this webhook uses Basic Auth instead of the OAuth credentials used for the api. Please contact integrations@qargo.com to request credentials. All `event_time`, `eta_start`, and `eta_end` date-time values must include a timezone offset, for example `2025-06-15T10:30:00Z` or `2025-06-15T12:30:00+02:00`. --- ## Identifying a stop Each update targets either a single **stop** or a **stop group**. Provide one per update entry. ### By stop ID (preferred) If you know the Qargo stop UUID, pass it directly in `stop.id`: ```json { "updates": [ { "stop": { "id": "a1b2c3d4-0000-0000-0000-000000000000", "status": "AT_STOP" }, "event_time": "2025-06-15T10:30:00Z" } ] } ``` ### By matching criteria When the stop ID is not known, use `stop.match` to find the stop by its related entities. The matcher uses **all provided criteria combined** (AND logic) and expects **exactly one stop** to match. If zero or multiple stops match, the update is discarded. Available matching fields: | Object | Field | Description | |----------------|------------------------------|------------------------------------------------------| | `trip` | `name.matches_any` | Trip name(s) | | `order` | `name.matches_any` | Order name(s) | | `order` | `customer_reference_number.matches_any` | Customer reference number(s) | | `order` | `id.matches_any` | Order UUID(s) | | `consignment` | `reference_number.matches_any` | Consignment reference number(s) | | `consignment` | `order_sequence_number` | Consignment sequence number within the order (integer) | | `stop` | `reference_number.matches_any` | Stop reference number(s) | | `stop` | `stop_type` | `PICKUP` or `DELIVERY` | Each `matches_any` field accepts a list of values — the stop matches if its value equals **any** of them. When multiple fields are provided, they are all required to match (AND). **Example — match by order reference + stop type:** ```json { "updates": [ { "stop": { "match": { "matches_all": [ { "order": { "customer_reference_number": { "matches_any": ["REF-12345"] } }, "stop": { "stop_type": "DELIVERY" } } ] }, "status": "COMPLETED" }, "event_time": "2025-06-15T14:00:00Z" } ] } ``` **Example — match by trip name + consignment reference:** ```json { "updates": [ { "stop": { "match": { "matches_all": [ { "trip": { "name": { "matches_any": ["T-20250615-001"] } }, "consignment": { "reference_number": { "matches_any": ["CONS-98765"] } } } ] }, "status": "AT_STOP", "eta_end": "2025-06-15T16:00:00Z" }, "event_time": "2025-06-15T14:30:00Z" } ] } ``` ## Stop group updates A stop group represents multiple stops grouped by activity and location. When updating via `stop_group`, the status applies to **all stops** in that group. The stop group `id` is always required — matching by criteria is not supported for stop groups. ```json { "updates": [ { "stop_group": { "id": "b2c3d4e5-0000-0000-0000-000000000000", "status": "COMPLETED" }, "event_time": "2025-06-15T16:00:00Z" } ] } ``` ## Statuses - `AT_STOP` — the vehicle has arrived at the stop location. - `COMPLETED` — the stop activity is finished. - *Omit* `status` to update only the ETA or data fields without changing the stop status. ## Request body - FleetStatusUpdatePayload - `updates` FleetDispatchStatusUpdate[], required — List of status updates for stops and stop groups - `stop` StopStatusUpdate, required — Update a stop from an external source. Can update status and data of a stop. Updates on the data happen based on the defined integration_data_mapping in the integration configuration. - `id` string, uuid, nullable — ID of the stop. If not known, use the `match` property instead. - `match` StopMatchTarget - `matches_all` StopMatchInput[] - `trip` TripMatch - `name` FieldMatchInput - … - `order` OrderMatch - `customer_reference_number` FieldMatchInput - … - `name` FieldMatchInput - … - `id` FieldMatchInput - … - `consignment` ConsignmentMatch - `reference_number` FieldMatchInput - … - `order_sequence_number` integer, nullable - `stop` StopMatch - `reference_number` FieldMatchInput - … - `stop_type` 'PICKUP' | 'DELIVERY' | 'DEPOT_LOAD' | 'DEPOT_UNLOAD' - `leg` LegMatch - … - `eta_start` string, date-time, nullable — Estimated arrival time (ETA) at the stop in UTC. Include a timezone offset, for example `Z` or `+02:00`. - `eta_end` string, date-time, nullable — Estimated departure time (ETD) from the stop in UTC. Include a timezone offset, for example `Z` or `+02:00`. - `status` 'AT_STOP' | 'COMPLETED' - `question_answers` object — Data related to the status update. This data can be mapped to different entities in Qargo. - `event_time` string, date-time, required — Time of the event in UTC. Include a timezone offset, for example `Z` or `+02:00`. - `stop_group` StopGroupStatusUpdate, required — Update a stop group from an external source. Can update status and data of the stops in a stop group. Updates on the data happen based on the defined integration_data_mapping in the integration configuration. - `id` string, uuid, required — ID of the stop group (from the original order/trip) - `status` 'AT_STOP' | 'COMPLETED' - `question_answers` object — Data related to the status update. This data can be mapped to different entities in Qargo. - `eta_start` string, date-time, nullable — Estimated arrival time (ETA) at the stop group in UTC. Include a timezone offset, for example `Z` or `+02:00`. - `eta_end` string, date-time, nullable — Estimated departure time (ETD) from the stop group in UTC. Include a timezone offset, for example `Z` or `+02:00`. ## Response `200` Successful Response - unknown ## Other responses - `400` — Bad Request — invalid input or malformed request - `401` — Unauthorized — missing or invalid authentication credentials - `403` — Forbidden — insufficient permissions for this operation - `422` — Validation Error - `429` — Too Many Requests — rate limit exceeded. See the `Retry-After` header - `500` — Internal Server Error - `503` — Service Unavailable — temporarily unable to handle the request --- [API](https://skmtc.dev/qargo/apis/qargo-tms-api.md) · [All operations](https://skmtc.dev/qargo/apis/qargo-tms-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/qargo/qargo-tms-api/revisions/17297902e7ce/schema)