External Status Update

Webhook for updating the status, ETA, and data of stops from an external subcontractor system.

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 a single stop. You can identify it by its Qargo UUID or by matching criteria.

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"
    }
  ]
}

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.