Go-live checklist

Test keys and live keys use the same base URL, payloads, and events. Switching means replacing the key and registering live webhook endpoints. Before you do, go through this list.

Keys#

• Create a separate live key per system that calls Maxmove, with only the permissions it needs (quotes:create, deliveries:read, deliveries:write, webhooks:manage). See Security.
• Store the key in your secret manager or environment, never in code, a mobile app, or a browser.
• Note who owns the key and when it expires, if you set an expiry date.

Workspace#

• Your workspace is approved for invoice billing. Without approval, live deliveries fail with 403 invoice_billing_not_enabled; contact Maxmove support.
• Every pickup and dropoff you plan to serve lies in the Maxmove service area. Outside it, requests fail with 400 service_area_unavailable.
• Your pickup locations have a contact with a phone number that someone answers during pickup hours.

Requests#

• Every create request sends an Idempotency-Key that is stable per order, and retries reuse it. See Idempotency.
• Every address comes with the coordinates of your address search.
• If you quote first, you book with the same route and scheduled_at within about 5 minutes, and handle quote_expired by quoting again.
• Your code branches on error.code, never on the message, and logs request_id with every failed call.
• Retries: 429, 502, and 503 are retried with backoff, honoring Retry-After. 409 request_in_progress is retried shortly. Other 4xx responses are not retried until the request is fixed. See Errors.

Webhooks#

• A live endpoint is registered with your live key. Test endpoints only receive test events.
• Your receiver verifies the signature over the raw body and rejects old timestamps. See Verify signatures.
• It answers 2xx within 5 seconds and does the work afterwards.
• It deduplicates on the event id and reads data.status instead of relying on arrival order.
• You know how to replay failed events after an outage with POST /v1/webhooks/{webhookId}/replay. See Retries.

Rehearse in test mode#

• A full test delivery reaches delivered in your system, including proof of delivery.
• Both failure scenarios (test_scenario: courier_cancelled and delivery_failed) end as cancelled in your system and reach a person.
• Cancelling before pickup works, and cancelling after pickup shows the 409 not_cancellable path.

First live deliveries#

• Book the first live deliveries during business hours, with a short route you can watch on the tracking page.
• Keep an eye on failed requests and webhook errors in your logs for the first days.