WEBHOOK Order Status

Description

This is an outbound call — Bigcity POSTs this payload to your registered webhook URL every time an order's status changes. EGV orders resolve in a single step; PHYSICAL orders go through a multi-step delivery lifecycle. Your endpoint should respond with a 2xx status to acknowledge receipt — Bigcity retries delivery on any non-2xx response.

Status values:

  • EGV: processing → success | failed
  • PHYSICAL: processing → shipped → delivered | rto | cancelled | failed

Headers (sent by Bigcity)

X-Bigcity-Signature

HMAC-SHA256 signature of the raw request body, computed using your webhook secret. Verify this before trusting the payload.

Content-Type

application/json

Payload Fields

order_id type: string

The order_id you supplied on v1/bigcity/create.

order_ref type: string

Bigcity's order reference (PHYSICAL orders only).

sku type: string

The line item SKU this status applies to.

product_type type: string

EGV or PHYSICAL.

previous_status / status type: string

The status transition that triggered this webhook.

tracking type: object, nullable

Present for PHYSICAL orders once shipped: courier, tracking_number, tracking_url. Null otherwise.

updated_at type: datetime

When the status changed.

Example Payload (Bigcity → Client)

{
  "order_id": "asdsa3432",
  "order_ref": "BCP-ORD-98213",
  "sku": "BC-MUG-BLUE-01",
  "product_type": "PHYSICAL",
  "previous_status": "processing",
  "status": "shipped",
  "tracking": {
    "courier": "BlueDart",
    "tracking_number": "BD123456789IN",
    "tracking_url": "https://bluedart.com/track/BD123456789IN"
  },
  "updated_at": "2026-07-06T18:00:00+05:30"
}

Expected Response (Client → Bigcity)

HTTP/1.1 200 OK