> 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/getting-started.md).

# Getting Started

Follow this guide to connect your backend to Dispatch on **staging**.

## Before you begin

You need:

* A **merchant account** on Dispatch (your organization’s login).
* A **backend service** you control (Node, Python, Java, etc.) that can store secrets and call HTTPS APIs.
* For webhooks: a **public HTTPS endpoint** (use [ngrok](https://ngrok.com/) or similar while developing locally).

## Staging URLs

| Resource           | URL                                            |
| ------------------ | ---------------------------------------------- |
| Merchant Dashboard | <https://merchants.staging.dispattch.dev>      |
| API base           | `https://service.staging.dispattch.dev/api/v1` |

Sign in to the dashboard with your merchant email and password. The dashboard is where you **create API keys** and **register webhooks**. Your application code uses the API key and webhook signing key—not your dashboard password.

***

## Step 1 — Create an API key

1. Open the [Merchant Dashboard](https://merchants.staging.dispattch.dev) and sign in.
2. In the sidebar, click **API Keys**.
3. Click **Generate New Key**, then **Generate Key**.
4. **Copy the key immediately.** It is shown only once. If you lose it, delete the key and generate a new one, then update your application configuration.

Store the key in a secret manager or environment variable (for example `DISPATCH_API_KEY`). See [API Keys](/integrate-with-dispatch/authentication-api-keys.md) for details.

***

## Step 2 — Call the API from your server

Every API request from your integration must include:

```http
X-API-KEY: dsp_your_key_here
```

Example: list your shipments:

```bash
curl -s "https://service.staging.dispattch.dev/api/v1/shipments?page=1&page_size=5" \
  -H "X-API-KEY: dsp_your_key_here"
```

Example: create a shipment:

```bash
curl -s -X POST "https://service.staging.dispattch.dev/api/v1/shipments" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: dsp_your_key_here" \
  -d '{
    "courier_company_id": 12,
    "start_address": "9.0123, 38.7465",
    "end_address": "9.0500, 38.8000",
    "description": "Order #10042",
    "weight_kg": 2.5,
    "items": ["Item A"]
  }'
```

A successful response returns shipment JSON including `code` and `status`. Full examples are in [API Keys](/integrate-with-dispatch/authentication-api-keys.md).

***

## Step 3 — Register a webhook

Webhooks let Dispatch **push** shipment updates to your server when status changes (for example driver assigned, delivered, cancelled).

1. In the Merchant Dashboard sidebar, click **Webhooks**.
2. Click **Register Webhook**.
3. Enter your **Target URL** — must be **HTTPS** and publicly reachable (for local dev, use an ngrok HTTPS URL).
4. Click **Save Webhook**.
5. On the success screen, **copy the Signing Key** immediately. It is shown only once. You need it to verify that requests really come from Dispatch.

See [Webhooks](/integrate-with-dispatch/webhooks.md) for how to implement your endpoint and verify signatures.

***

## Step 4 — Receive a test webhook

1. Implement a `POST` handler on your HTTPS URL that:
   * Reads the raw request body.
   * Verifies the `X-Dispatch-Signature` header (see [Webhooks](/integrate-with-dispatch/webhooks.md)).
   * Returns HTTP `200` (or any status below `400`) quickly after saving the event.
2. Create or update a shipment in staging (via API or dashboard) and move it through a status change (for example assign a driver).
3. Confirm your server logs show the JSON payload and a valid signature.

***

## What to read next

* [API Keys](/integrate-with-dispatch/authentication-api-keys.md) — all operations you can call with your key, rotation, security.
* [Webhooks](/integrate-with-dispatch/webhooks.md) — payload format, verification code, testing, troubleshooting.
* [Integration Checklist](/integrate-with-dispatch/integration-checklist.md) — before you switch to production.


---

# 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/getting-started.md?ask=<question>&goal=<endgoal>
```

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