Skip to content

Use case / Fleet dispatch

Required api role: not applicable (push/push)

Purpose: This interface allows an external party to integrate with driver apps and on board computer systems.

The fleet 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 send 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 Upload From A Fleet Application

Request

Upload a document to a specific stop or stop group on a fleet-dispatched 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_idNo*The Qargo UUID of the stop to attach the document to
stop_group_idNo*The Qargo UUID of the stop group to attach the document to

*Provide either stop_id or stop_group_id to identify where to attach the document.

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/fleet-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 or null(Stop Id)
Any of:

The stop ID to which the document is related

string
stop_group_idstring or null(Stop Group Id)
Any of:

The stop group ID to which the document is related

string
Bodyapplication/jsonrequired
Any of:

A single binary file or JSON message

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

Responses

Successful Response

Bodyapplication/json
any
Response
// No response example