DropHub External API

The External API is the machine-to-machine surface of DropHub. There are eleven endpoints. A merchant system authenticates as an OAuth client, creates a shipment from an order reference and two coordinates, and receives signed webhook events as the shipment moves.

Quickstart

Token to delivered shipment in four calls.

Authentication

Client credentials, three scopes, token lifecycle.

Shipments

The minimal create request and what comes back.

Webhooks

One endpoint, seven events, HMAC-SHA256 signatures.

What you send

Everything DropHub needs to move a parcel:

{
  "reference": "ORDER-1042",
  "pickup": { "latitude": 24.7136, "longitude": 46.6753 },
  "destination": { "latitude": 24.774265, "longitude": 46.738586 },
  "recipient": { "name": "Noura", "mobile": "0551234567" }
}

What DropHub derives

You do not model any of the following, and there is no API for configuring them. DropHub resolves each one internally when the shipment is created:

Derived	Meaning
Address and city context	Reverse-geocoded from the two coordinates
Route and distance	Computed between pickup and destination
Coverage	Whether the lane is serviceable, decided at creation
Price	Priced against your account’s commercial terms
Carrier	Selected and dispatched without your involvement
Service and defaults	One-piece, 1 kg ambient parcel, SAR, prepaid, unless you say otherwise
Lifecycle state	Advanced by real events from the field
Tracking URL	Minted for you and returned on the create response

There is no quote step, no branch or pickup directory to read, no carrier to pick, no coverage to configure, and no tracking link to mint. If you are looking for one of those, it is because DropHub already did it.

The whole surface

Endpoint	Purpose
`POST /oauth/token`	Exchange client credentials for a bearer token
`POST /v2/external/shipments`	Create a shipment
`GET /v2/external/shipments/{id}`	Read a shipment
`GET /v2/external/shipments/{id}/tracking`	Read progress and driver location
`POST /v2/external/shipments/{id}/cancel`	Cancel before a driver is assigned
`POST /v2/external/webhook`	Configure your webhook
`GET /v2/external/webhook`	Read your webhook
`PATCH /v2/external/webhook`	Change URL, events, or pause state
`DELETE /v2/external/webhook`	Remove your webhook
`POST /v2/external/webhook/secret-rotations`	Rotate the signing secret
`GET /v2/public/tracking/{code}`	The customer-facing tracking view, unauthenticated

Conventions

Idempotency and ETags

Your order reference is the retry key. If-Match guards webhook changes.

Errors

RFC 9457 problem details with stable machine codes.

Responses are JSON. Errors are application/problem+json. Timestamps are UTC and ISO 8601. Money is an exact decimal in SAR — never a floating-point number.

Getting Started

Authentication

Shipments

Events

Request semantics

API reference

Quickstart

Authentication

Shipments

Webhooks

What you send

What DropHub derives

The whole surface

Conventions

Idempotency and ETags

Errors

Quickstart

Authentication

Shipments

Webhooks

​What you send

​What DropHub derives

​The whole surface

​Conventions

Idempotency and ETags

Errors

What you send

What DropHub derives

The whole surface

Conventions