Order Status Callbacks
In addition to Live Order Location GPS pushes, Shadowfax provides a generic Push Callback API for both Marketplace (seller pickup) and warehouse models — enable it to get real-time notification whenever an order's status changes.
Order States
An order can be in one of the following states. This state is shared in the status_id field on the Order Tracking APIs, and as event on this callback.
status_id | Status | Remark | Description |
|---|---|---|---|
assigned_for_delivery | Assigned for Customer Delivery | Item Assigned at <SFX Facility> | Order is assigned to a Shadowfax rider for customer delivery. |
ofd | Out For Delivery | Item OFD at <SFX Facility> | Order is out for customer delivery. |
arrived_customer_doorstep | Arrived At Customer Doorstep | Arrived At Customer Doorstep | Rider has arrived at the customer's doorstep. |
delivered | Delivered | Item Delivered at <SFX Facility> | Order has been delivered to the customer. |
nc | Not Contactable | Customer not contactable | Customer is not contactable for delivery. |
na | Not Attempted | Rider not attempted order | Customer delivery was not attempted by the Shadowfax rider. |
cancelled_by_customer | Cancelled | Order cancelled by customer | Delivery request has been cancelled by the customer (various reasons). |
rts_d | Returned To Client | Item Return To Seller Delivered at <Store/Facility> | Order has been successfully returned to the seller. |
cid | Cid | Customer wants delivery on another date | Customer Initiated Delay — customer has requested delivery on another day. |
on_hold | On Hold | Payment Issue | Item is put on hold due to client/operational concerns. |
Callback Headers
The standard callback carries an optional authentication header plus Content-Type:
Code
Header keys can be added or modified per client — for example:
Code
Configure the callback URL and headers via the Webhook tab in the Client Portal.
Field Reference
| Field | Description |
|---|---|
awb_number | Generated by Shadowfax while placing an order |
order_id | client_order_id shared while placing the order |
event_timestamp | Timestamp of the current status, YYYY-MM-DD HH:MM:SS |
current_location | Current location of the order at the time of the event |
comments | Remarks associated with the status |
status | Current status of the shipment |
event | Current status_id of the shipment |
otp_verified | Whether the status was marked after OTP verification — Y, N, or NA (default NA) |
rider_name | Name of the delivering rider. Shared only when the current status is ofd |
rider_contact | Contact number of the delivering rider. Shared only when the current status is ofd |
type | Order type, e.g. FWD / REV |
recipient_info | Proof of delivery — sent only when the current status is delivered or rts_d |
client_id | Shadowfax-assigned client identifier |
rider_latitude / rider_longitude | Rider's location at the time of the event. Observed on ofd and arrived_customer_doorstep events |
delivery_eta | Estimated minutes to delivery. Observed on ofd events |
tracking_link | Public tracking URL for the shipment. Observed on ofd events |
Example Payload
Combined example showing the full field set — rider_latitude/rider_longitude/delivery_eta/tracking_link (populated on ofd) alongside the structured recipient_info object (populated on delivered/rts_d). Not every field is present on every event — see the descriptions above for when each one is populated.
Code
Best Practices
- Return
200immediately, process the payload asynchronously. - Implement idempotency — use
(awb_number, event)or(awb_number, event_timestamp)as a dedupe key, since the same event may be delivered more than once. - Use
order_idto reconcile against your ownclient_order_id— note it maps to thecoidfield on the Live Order Location push. - Log the raw payload before processing for debugging.