> For the complete documentation index, see [llms.txt](https://dispatch-2.gitbook.io/integrate-with-dispatch/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dispatch-2.gitbook.io/integrate-with-dispatch/reference.md). # Reference Quick reference for developers integrating with Dispatch on **staging**. ## URLs | Resource | Staging URL | | ------------------ | ---------------------------------------------- | | API base | `https://service.staging.dispattch.dev/api/v1` | | Merchant Dashboard | | Production URLs are provided by your Dispatch account team. *** ## Headers ### API requests (your server → Dispatch) | Header | Value | | -------------- | --------------------------------------------- | | `X-API-KEY` | Your API key (`dsp_...`) | | `Content-Type` | `application/json` (for requests with a body) | ### Webhook requests (Dispatch → your server) | Header | Value | | ---------------------- | -------------------------------------------------- | | `Content-Type` | `application/json` | | `X-Dispatch-Signature` | `sha256=` + HMAC-SHA256 hex digest of **raw body** | *** ## Shipment status values Webhook payloads include a `status` field. Common values: | Status | Meaning | | --------------------- | -------------------------------------------------- | | `assigned_to_courier` | Shipment created and assigned to a courier company | | `assigned_to_driver` | A driver has been assigned | | `in_transit` | Driver picked up the shipment | | `delivered` | Delivery completed | | `failed` | Delivery attempt failed | | `returned` | Shipment returned | | `cancelled` | Shipment cancelled | | `pending` | Early state (may appear depending on workflow) | Treat each webhook body as the **current** state of the shipment. *** ## API key endpoints All paths are relative to `https://service.staging.dispattch.dev/api/v1`.\ Send `X-API-KEY` on every request. | Method | Path | Description | | ------ | --------------------------------------------- | ------------------------------------------------------------------ | | `POST` | `/shipments` | Create shipment | | `GET` | `/shipments` | List shipments (query: `page`, `page_size`, `status`, dates, etc.) | | `GET` | `/shipments/:code` | Get one shipment | | `POST` | `/shipments/:code/cancel` | Cancel shipment | | `POST` | `/shipments/:code/generate-confirmation-code` | Generate delivery confirmation code | | `POST` | `/shipments/:code/rate` | Rate delivered shipment (body: `{ "rating": 1-10 }`) | | `GET` | `/merchant-couriers` | List couriers available to your merchant | *** ## HTTP errors | Code | Typical meaning for integrators | | ----- | ------------------------------------------------------------- | | `400` | Invalid request body, invalid ID, or webhook URL not HTTPS | | `401` | Missing or invalid API key | | `403` | Resource does not belong to your merchant account | | `404` | Shipment or resource not found | | `409` | Webhook URL already registered for your merchant | | `5xx` | Dispatch or network issue—retry idempotent reads with backoff | *** ## FAQ ### Do I use my dashboard password in API calls? No. Use an **API key** in the `X-API-KEY` header. Your password is only for signing into the Merchant Dashboard. ### I lost my API key. Can I view it again? No. Generate a new key in **API Keys**, update your servers, then delete the old key. ### I lost my webhook signing key. What do I do? Delete the webhook in the dashboard, register the URL again, and copy the new signing key. Update your server configuration. ### Can I use `http://localhost` for webhooks? Not directly. Dispatch requires **HTTPS**. For local development, use a tunnel (ngrok, Cloudflare Tunnel, etc.) and register the **HTTPS** tunnel URL. ### Why did I stop receiving webhooks? Check that your URL is still registered, returns a status **below 400**, and is reachable from the internet. Failed deliveries are not automatically retried—fix the endpoint and monitor new shipment events. ### Are webhook payloads partial updates? No. Each delivery contains a **full shipment JSON object** reflecting the current state. ### Can I call every Dispatch API with an API key? No. Key management and webhook registration use **dashboard login**. Shipment and merchant-courier operations listed above use **API keys**. See [API Keys](/integrate-with-dispatch/authentication-api-keys.md). ### What is the difference between `webhook_url` on create shipment and dashboard webhooks? When creating a shipment you may pass an optional per-shipment `webhook_url` field in the API body. **Merchant webhooks** (this documentation) are account-level endpoints registered under **Webhooks** in the dashboard and receive updates when shipment state changes through the platform. Use the dashboard webhooks for a single integration endpoint for all shipments. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://dispatch-2.gitbook.io/integrate-with-dispatch/reference.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.