Get started

Use this page to establish the production endpoint, protect integration secrets, and test the outcomes your backend owns before release.

Prerequisites

• A backend service that can make HTTPS requests or receive HTTPS POSTs.
• Server-side secret storage for webhook signing secrets.
• A receiver endpoint that can retain the raw request body before JSON parsing if you use Webhooks.

Use the production API host

All production API URLs begin with:

https://mexpress.nz/api/v1

https://docs.mexpress.nz is documentation, not an API host.

Implement in this order

1. Implement Public Tracking against a known tracking_number; handle 200, neutral 404, and 429.
2. If your service needs delivery-driven updates, implement Webhooks: retain raw bytes, verify the signature, and persist event_id before a side effect.
3. Make retries safe. Poll tracking conservatively; make webhook event handling idempotent and order customer-facing changes by scanned_at.
4. Add alerts that report failures without logging secrets or full sensitive payloads.

Keep secrets in backend code only

Webhook signing secrets are production secrets. Store them in your server-side secret manager, select them by X-Delivery-Webhook-Key-Id, and redact them from logs and support material. Do not embed them in browser code, a mobile app, source control, or client-visible configuration.

If you suspect exposure, stop trusting the affected secret and complete your secret-rotation process before resuming event processing.

Acceptance checklist

• [ ] API requests use https://mexpress.nz/api/v1, not the documentation host.
• [ ] A successful tracking request is shown using only the returned safe projection.
• [ ] Unknown or unavailable tracking is one neutral 404 user outcome.
• [ ] 429 handling honours Retry-After and does not tight-loop.
• [ ] The webhook receiver validates the unchanged raw body before parsing it.
• [ ] event_id is persisted durably before its business effect.
• [ ] Duplicate and out-of-order events are safe to process.
• [ ] Monitoring records failure category, never signing material.

Common mistakes

Do this	Not this
Send API requests to mexpress.nz/api/v1	Send requests to docs.mexpress.nz
Verify HMAC over original bytes	Re-serialize parsed JSON before verifying
Treat 404 as neutral unavailability	Reveal why a tracking number is unavailable
Defer work after a quick 2xx	Keep the sender waiting on slow downstream work

Next step

Choose Public Tracking for a lookup flow, or Webhooks for event-driven integration.