# 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.

---

## 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:

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


## 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.

Endpoint: POST /v1/webhook/subco-status-update
Version: 1.2.0
Security: BasicAuthWebhookCredentials

## Request fields (application/json):

  - `updates` (array, required)
    List of status updates for stops

  - `updates.stop` (object, required)
    Update a stop. Can update status and data of a stop.
        Updates on the data are based on a mapping defined in Qargo

  - `updates.stop.id` (any)
    ID of the stop. If not known, use the match property instead.

  - `updates.stop.match` (any)
    Matching criteria for the stop to update when the id is not known. This will attempt to find a match to a single stop using provided filtering criteria. If multiple stops are matched, this update will be discarded

  - `updates.stop.eta_start` (any)
    Estimated arrival time (ETA) at the stop in UTC.

  - `updates.stop.eta_end` (any)
    Estimated departure time (ETD) from the stop in UTC.

  - `updates.stop.status` (any)
    Updated status of the stop.

  - `updates.stop.question_answers` (object)
    Data related to the status update. This data can be mapped to different entities in Qargo.

  - `updates.event_time` (string, required)
    Time of the event in UTC

## Response 422 fields (application/json):

  - `detail` (array)

  - `detail.loc` (array, required)

  - `detail.msg` (string, required)

  - `detail.type` (string, required)


## Response 400 fields

## Response 401 fields

## Response 403 fields

## Response 429 fields

## Response 500 fields

## Response 503 fields