Status updates, retries, and webhooks

The Partner API exposes current delivery state through both read endpoints and signed webhooks.

Read delivery status#

• GET /partner/v1/deliveries/{id} returns the complete delivery resource.
• GET /partner/v1/deliveries/{id}/tracking returns status, ETA, remaining distance, route polyline, and the available courier position.
• GET /partner/v1/deliveries lists deliveries with cursor pagination through page_token.

Supported states are pending, courier_assigned, at_pickup, picked_up, in_transit, at_dropoff, delivered, cancelled, and expired.

Read endpoints remain the reliable path for initial loading, reconnects, and reconciliation after a missed event. Webhooks provide immediate notifications.

Use webhooks#

Register an HTTPS endpoint with POST /partner/v1/webhooks. Subscribe to all or selected events:

• delivery.created
• delivery.status_updated
• delivery.courier_assigned
• delivery.courier_arrived
• delivery.eta_updated
• delivery.pod_submitted
• delivery.delivered
• delivery.cancelled

The whsec_… signing secret is returned only when the endpoint is created or its secret is rotated. Verify x-signature using the event id, delivery id, timestamp, and SHA-256 hash of the unchanged raw request body. Also validate x-event-timestamp against a short acceptance window.

Delivery and retries#

• Webhooks are delivered at least once. Deduplicate using x-event-id or the event id in the body.
• Network failures, 408, 409, 425, 429, and 5xx responses are retried with exponential backoff and jitter.
• After eight failed attempts, the delivery enters the dead-letter queue.
• Use POST /partner/v1/webhooks/{id}/replay to requeue failed deliveries.
• Return a successful 2xx response quickly and perform longer processing asynchronously.

Treat webhooks as a signal and reconcile against the delivery or tracking resource whenever the current state is uncertain.