---
title: "External Status Update"
method: POST
path: "/v1/webhook/subco-status-update"
tags: ["Use case / Subcontractor dispatch", "Webhooks / Inbound"]
---

# External Status Update

`POST /v1/webhook/subco-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`:

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

## Request body

- SubcontractorStatusUpdatePayload
  - `updates` BaseStatusUpdate[], required — List of status updates for stops
    - `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`.

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