Skip to content

Use case / Subcontractor dispatch

Required api role: not applicable (push/push)

Purpose: This interface allows an external party to integrate with 3rd party transport management systems for subcontracting.

The subcontractor dispatch uses a push/push model: Qargo pushes a dispatch payload to an external endpoint. The third party then updates Qargo using our webhook endpoint:

dispatch flow

Subsequent updates or cancellations will also be sent via this webhook, using the same payload format. The dispatch format has the following structure:

dispatch payload

The destination of this webhook can be a RESTful interface or file base protocol like SFTP

The status update endpoint can be used to receive information about the stops back to Qargo. Status update date-time values, including event_time, eta_start, and eta_end, must include a timezone offset such as Z or +02:00.

Operations

External Document Update With Payload

Request

Upload a document to a specific stop on a subcontracted trip.

This webhook uses Basic Auth (webhook credentials), not the OAuth credentials used for the API. Contact integrations@qargo.com to request credentials.

Query parameters

ParameterRequiredDescription
question_path_keyYesMaps the file to a document type in Qargo (e.g. CMR, POD, WEIGHT_NOTE)
stop_idYesThe Qargo UUID of the stop to attach the document to

Headers

HeaderRequiredDescription
Content-TypeYesMIME type of the file (e.g. application/pdf, image/jpeg)
Content-DispositionNoProvides the filename: attachment; filename="POD.pdf"

Filename handling

The uploaded file's name in Qargo is determined by:

  1. If Content-Disposition includes a filename — that value is used, combined with the question path key default. For example: filename="pod1234.pdf" with question path key default POD.pdf → stored as pod1234_POD.pdf.
  2. If no Content-Disposition is provided — the default filename from the question path key configuration is used.

Example

curl -X POST \
  "https://api.qargo.com/v1/webhook/subco-document-upload\
  ?question_path_key=POD&stop_id=<stop_uuid>" \
  -u "<webhook_client_id>:<webhook_secret_id>" \
  -H "Content-Type: application/pdf" \
  -H "Content-Disposition: attachment; filename=POD.pdf" \
  --data-binary @/path/to/document.pdf
Security
BasicAuthWebhookCredentials
Query
question_path_keystring(Question Path Key)required

The question path key to map the file in Qargo, for example: CMR/POD

stop_idstring(Stop Id)required

The stop ID to which the document is related

Bodyapplication/jsonrequired
Any of:

A single binary file or JSON message

string (binary)
POST
/v1/webhook/subco-document-upload
"string"

Responses

Successful Response

Bodyapplication/json
any
Response
// No response example