Webhooks
When you configure a callback_url during order creation or in your partner dashboard, Pathao will push real-time status updates to your server via HTTP POST requests. This eliminates the need for polling and ensures your system stays synchronized with the delivery lifecycle.
Webhook Events
The following events are sent to your callback URL as the order progresses through its lifecycle.
| Event Type | Trigger | Payload Includes |
|---|---|---|
ORDER_CREATED | Order successfully created | order_id, status, quotation, tracking_url |
ASSIGNED | Order assigned to driver | order_id, status, driver_info |
ACCEPTED | Driver accepts order | order_id, status, driver_info, eta |
STARTED | Driver starts journey to pickup | order_id, status, eta |
PICKED | Driver confirms parcel pickup | order_id, status, timestamp |
COMPLETED | Delivery confirmed | order_id, status, timestamp |
CANCELLED | Order cancelled | order_id, status, cancellation_reason |
Webhook Payload Example
Each webhook request sends a JSON payload in the POST body. Your endpoint should respond with a 200 OK status within 5 seconds to acknowledge receipt.
Order Status State Machine
Orders move through the following states. Cancellation is possible from any pre-PICKED status.
Retry Policy
Failed webhooks are retried up to 5 times with exponential backoff. After all retries are exhausted, the webhook is queued for manual review. Partners can use the status polling endpoint as a fallback.
| Attempt | Delay After Failure |
|---|---|
| Retry 1 of 5 | 1s |
| Retry 2 of 5 | 2s |
| Retry 3 of 5 | 4s |
| Retry 4 of 5 | 8s |
| Retry 5 of 5 | 16s |
Best Practices
- 1Respond quickly. Return a 200 status within 5 seconds. Process the payload asynchronously if your logic takes longer.
- 2Handle duplicates. Webhooks may be delivered more than once. Use the
order_idandparcel_statuscombination as a deduplication key. - 3Verify the source. Validate that the request comes from Pathao by checking the originating IP or implementing a shared secret header.
- 4Use status polling as fallback. If your webhook endpoint goes down, use the
GET /v1/business/order/:id/statusendpoint to reconcile any missed updates. - 5Log everything. Store the raw webhook payload alongside your processed data for debugging and auditing purposes.