Receive order updates with webhooks

MiniDrop sends an order.updated notification to your HTTPS endpoint whenever an order changes: created, assigned, picked up, delivered, cancelled and so on. Build your receiver against the payload below.

Set it up#

1. Expose a public HTTPS endpoint that accepts POST with a JSON body.

2. In the outlet portal, open Developers. Enter your Webhook URL and, optionally, a Secret (optional). Keep Enable webhook on and press Save webhook.

3. On each request, verify X-API-SECRET if you set a secret, read the payload and update your system using order_id or reference_order_id.

4. Answer with a 2xx quickly. You can keep processing on your side afterwards.

Close

For testing, the Sandbox webhook URL (optional) and Sandbox webhook secret (optional) fields are used for practice-server order updates.

The request#

MiniDrop sends POST to your URL with these headers:

Content-Type: application/jsonX-API-SECRET: <your-webhook-secret>   # only if you set a secret

The delivery_charge and total_amount values in this sample are placeholders.

{  "event": "order.updated",  "timestamp": "2025-02-21T10:00:30.000Z",  "data": {    "order_id": "550e8400-e29b-41d4-a716-446655440000",    "outlet_id": "550e8400-e29b-41d4-a716-446655440001",    "status": "ASSIGNED",    "distance_km": 5.2,    "delivery_charge": 0,    "total_amount": 0,    "customer_name": "Customer Name",    "customer_phone": "+919876543210",    "reference_order_id": "POS-12345",    "delivery_executive": {      "id": "550e8400-e29b-41d4-a716-446655440002",      "name": "Rider Name",      "phone": "+919876543210"    },    "track_url": "https://minidrop.in/t/Qm3k9x_2LrT7vH1aBn0pWg"  }}

The customer tracking link#

When a rider is assigned, the order gets a track_url. It appears in the webhook (data.track_url), in GET /api/orders/:id and in the order entries of the /api/trips responses. Send it to your customer by SMS, WhatsApp or in your app. It opens a mobile page that shows only that customer’s delivery: progress, the shop pin, the customer’s own drop pin and a short address, the rider’s first name and (if enabled for your outlet under Business profile) a Call button, and the rider’s live position and an ETA range only while the rider is on the way to that customer.

Other customers’ addresses, names, phones and positions, the pickup code and amounts are never shown.

• The key is always present in the webhook. It is null for CREATED orders, orders cancelled before assignment, and orders in a batch that is still PENDING_APPROVAL.

• The link is stable: the same order always returns the same track_url.

• The link stops working 24 hours after the order is delivered, undelivered or cancelled. The page then says it has expired.

• Treat the URL as opaque. Do not parse it.

• In the sandbox, track_url points at a static demo page.

For the shop side of this, see Share the live tracking link with your customer.

Delivery and retries#

• Asynchronous. Order updates are never blocked by your webhook.

• Retries. Up to 3 retries with backoff of 1 s, 5 s and 15 s on network errors, 5xx and 408.

• No retry on other 4xx responses. Return 2xx when you accept the event.

• Durable. Each update is stored before it is sent, so updates and their pending retries survive a restart or deploy on MiniDrop’s side.

• Idempotency. The same update may arrive more than once. Treat deliveries as idempotent.

Security#

• Use HTTPS for webhook URLs.

• Set a secret and reject requests whose X-API-SECRET does not match.

• Use the separate sandbox webhook URL while testing, with the same receiver logic.