Core
Callbacks
Shadowfax sends POST callbacks to your registered URL whenever a forward order changes state. Your endpoint must be served over HTTPS.
Payload Format
Unlike the rest of this API, the callback payload is not a single fixed schema — it's a template configured per client during integration, built from placeholder substitution. Your account manager sets this up with you and confirms the exact field names and shape your endpoint will receive. Available placeholders include:
| Placeholder | Description |
|---|---|
{client_order_id} | Your order ID |
{awb_number} | Shadowfax AWB number |
{status} | Human-readable status text |
{status_id} | Machine-readable status code (see Order Lifecycle) |
{remarks} | Additional context for the event |
{current_location} | Hub or location where the event occurred |
{rider_name} / {rider_contact} | Assigned rider details, where applicable |
{delivery_otp} | Delivery OTP, for orders using OTP-based delivery confirmation |
{cancellation_remarks} | Populated when the order was cancelled by the customer |
{total_amount} / {payMode} / {codAmount} | Order value and payment details |
{created_date} / {created_time} / {updated_date} / {updated_time} | Order timestamps (IST) |
{last_updated} | Timestamp of the current status change (IST) |
{otp_verified} | Whether the event was confirmed via OTP — Y/N/NA |
{client_id} | Your Shadowfax client ID |
{recipient_info} | Proof-of-delivery details (recipient name, contact, signature) — populated on delivered/rts_d |
{estimatedDeliveryDate} | The order's promised delivery date, if set |
{shipmenttype} | F for forward leg, R for an RTS/return leg |
An example payload built from these might look like:
Code
Callback Behavior
| Aspect | Detail |
|---|---|
| Method | POST |
| Content-Type | application/json |
| Expected response | 200 OK |
| Timeout | Shadowfax waits up to 10 seconds for your endpoint to respond |
| Retry | Not automatic — a failed callback delivery is not retried. Use Tracking to reconcile anything your endpoint missed |
Common Events
Callbacks fire on the status transitions below (see Order Lifecycle for the full state list):
| Status | When |
|---|---|
Assigned for Pickup | Order assigned to a rider for seller/warehouse pickup |
Picked | Item picked up from seller/warehouse |
Received at Forward Hub | Item dispatched between hubs |
Assigned for Customer Delivery / Out For Delivery | Rider assigned or en route to customer |
Delivered | Item delivered successfully |
Cid / Not Contactable / Not Attempted / On Hold | Delivery attempt failed — see Order Lifecycle |
Require Delivery - NDR | A failed delivery was reopened for another attempt |
Return to Seller initiated / Returned To Seller | RTS in progress / completed |
Cancelled | Order cancelled by customer |
Configuration
Register your webhook URL with your Shadowfax account manager during integration. You can configure separate URLs for forward and reverse orders.
Best Practices
- Return
200immediately, process the payload asynchronously. - Implement idempotency — the same event may be delivered more than once.
- Use Tracking as a reconciliation fallback — there's no automatic retry if your endpoint errors or times out.
- Log the raw payload before processing for debugging.
Last modified on