> 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/integration-checklist.md).

# Integration Checklist

Use this checklist before pointing **your production systems** at Dispatch. Complete each item on **your** side—the services you operate, not Dispatch internal setup.

## API key setup

* [ ] API key created in the Merchant Dashboard and stored in a secret manager (not in source code).
* [ ] Key is loaded only on **backend** servers (never in browser or mobile app code).
* [ ] Staging tested: at least one successful `POST /shipments` and `GET /shipments` with `X-API-KEY`.
* [ ] Production API key issued and configured separately from staging (when your account team provides production URLs).
* [ ] Rotation plan documented (generate new key → deploy → delete old key).

## Webhook setup

* [ ] Webhook URL registered in the Merchant Dashboard (**HTTPS** only).
* [ ] Signing key copied once and stored securely next to your API key.
* [ ] Handler verifies `X-Dispatch-Signature` on the **raw** request body.
* [ ] Handler returns HTTP status **below 400** within a few seconds after persisting the event.
* [ ] Heavy processing runs **after** the HTTP response (queue, background job, etc.).
* [ ] Idempotency implemented (upsert by shipment `code`, tolerate duplicate deliveries).

## Application behavior

* [ ] Your system maps Dispatch `status` values to your order/shipment workflow.
* [ ] Errors from Dispatch (`401`, `403`, `400`, `5xx`) are logged with enough context to debug (without logging full secrets).
* [ ] Timeouts and retries configured for outbound API calls (with backoff).
* [ ] Monitoring alerts if expected webhooks stop arriving for active shipments.

## Security review

* [ ] No API keys or signing keys in Git, CI logs, or client-side bundles.
* [ ] Webhook endpoint rejects requests with invalid or missing signatures.
* [ ] TLS valid on your webhook URL (trusted certificate, not expired).

## Staging sign-off

* [ ] End-to-end test: create shipment via API → receive webhook on status change → signature validates.
* [ ] Cancel or fail path tested if your business needs those flows.
* [ ] Runbook written for your team: key rotation, webhook URL change, signing key loss.

## Production cutover

* [ ] Production API base URL and dashboard URL confirmed with your account team.
* [ ] Production API key and webhook URL registered (separate from staging).
* [ ] Staging keys disabled or not used in production deployments.

When all items are checked, your integration is ready for live merchant traffic on your platform.


---

# 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/integration-checklist.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.