External Status Update From A Fleet Application

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:

{
  "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:

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:

{
  "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:

{
  "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.

{
  "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.