Seller Webhooks

Receive real-time warehouse events (orders, shipments, returns, and more) at your own endpoints. This guide covers event types, payloads, security, and setup.

Overview

NBOX automatically forwards events from the warehouse management system (WMS) to your webhook endpoints. You choose which event types to receive and configure a separate URL for each.

Event-based
Subscribe only to events you need

Signed payloads
HMAC-SHA256 on every delivery

Auto-retry
Up to 3 attempts with backoff

3 webhook types
Order, Shipment, Return

How It Works

1An event occurs in the WMS (e.g., new order, stock update, return)

2The event is mapped to a webhook type based on your configuration

3The payload is signed with your webhook secret (HMAC-SHA256)

4A POST request is delivered to your configured URL

Webhook Types & Events

Each webhook type has its own URL. You only receive events for the types you enable.

Type	Events
`order`	`order.new.event` `order.update.event` `order.invoice-update.event` `order.sync.event`
`shipment`	`order.shipment.event` `order.shipment.event`
`return`	`return.request.create.event` `return.request.approve.event` `return_order.create.event` `return_order.qc.event` `return_order.shipment.event`

Order Lifecycle

An order moves through these statuses. Webhook events fire at the highlighted stages.

Webhook Type	Event Name	Description
order	`order.new.event`	New Order `created` Order has been created in the system
order	`order.update.event`	Picked `picked` All items picked from warehouse shelves Packed `packed` Items packed and ready for shipment booking Ready To Ship `ready_to_ship` Shipment booked with carrier, awaiting pickup On Hold `on_hold` Order temporarily paused (e.g., address issue, payment review) Cancelled `cancelled` Order has been cancelled and will not be fulfilled
shipment	`order.shipment.event`	Shipped `shipped` Order assigned to a driver for delivery Delivered `delivered` Order successfully delivered to the customer

Return Order Lifecycle

All return events route to the return webhook type.

Request CreatedRequest ApprovedReturn CreatedReturn ShippedQC Completed

Webhook Type	Event Name	Description
return	`return.request.create.event`	Request Created Return request submitted for review
return	`return.request.approve.event`	Request Approved Request approved, ready for return order
return_order	`return_order.create.event`	Return Created Return order created in warehouse `data.status` — `Initiated` `data.refund_status` — `Pending` `data.oms_qc_status` — `Pending`
return_order	`return_order.shipment.event`	Return Shipped Return shipment dispatched to origin `data.status` — `Return To Origin`
return_order	`return_order.qc.event`	QC Completed Returned items inspected and QC done `data.status` — `qc_processed` `data.oms_qc_status` — `completed` or `failed` `data.refund_status` — `Refunded`, `Partial`, or `Pending`

Sample Payloads

Click each event type to see an example payload. Actual payloads may contain additional fields.

Order Event — order.new.event

Sent when a new order enters the system. The raw WMS payload is forwarded as-is.

{
  "event_name": "order.new.event",
  "data": {
    "id": "6a04307f8a05ecb9c0382168",
    "order_id": "ORD-20260513-001",
    "order_alias": "#1001",
    "status_code": "created",
    "type": "b2c",
    "source": "sales_channel",
    "seller_code": "SELLER_A",
    "seller": {
      "code": "SELLER_A",
      "name": "My Store"
    },
    "hub_code": "HUB-QA-01",
    "total": 99.98,
    "payment_method": "COD",
    "shipment_type": "delivery",
    "delivery_type": "normal",
    "require_shipping": true,
    "order_created_at": "2026-05-13T10:30:00Z",
    "updated_at": "2026-05-13T10:30:01.075559066Z",
    "customer": {
      "first_name": "Ahmed",
      "last_name": "Al-Rashid",
      "email": "ahmed@example.com",
      "mobile": "+974-55001234",
      "mobile_code": "+974"
    },
    "shipping_address": {
      "first_name": "Ahmed",
      "last_name": "Al-Rashid",
      "phone": "+974-55001234",
      "address1": "Building 5, Street 10",
      "address2": "",
      "city": "Doha",
      "state": "Ad Dawhah",
      "state_code": "QA-DA",
      "country": "Qatar",
      "country_code": "QA",
      "zip": "12345",
      "latitude": 25.2854,
      "longitude": 51.531,
      "display_city": "",
      "country_calling_code": "+974",
      "national_address_code": ""
    },
    "billing_address": {
      "first_name": "Ahmed",
      "last_name": "Al-Rashid",
      "phone": "+974-55001234",
      "address1": "Building 5, Street 10",
      "address2": "",
      "city": "Doha",
      "state": "Ad Dawhah",
      "state_code": "QA-DA",
      "country": "Qatar",
      "country_code": "QA",
      "zip": "12345",
      "latitude": 25.2854,
      "longitude": 51.531,
      "display_city": "",
      "country_calling_code": "+974",
      "national_address_code": ""
    },
    "order_items": [
      {
        "sku_code": "SKU-001",
        "sku_id": "sku-wms-id",
        "hs_code": "",
        "quantity": 2,
        "picked_quantity": 0,
        "packed_quantity": 0,
        "unit_price": 49.99,
        "selling_price": 49.99,
        "display_price": 49.99,
        "subtotal": 99.98,
        "total": 99.98,
        "discount": 0,
        "tax": 0,
        "tax_percent": 0,
        "tax_inclusive": false,
        "is_substituted": false,
        "item_barcodes": [],
        "serialised_sku_codes": [],
        "sales_channel_order_item_id": "SKU-001",
        "substitute_seller_sku_codes": []
      }
    ],
    "invoice": {
      "currency": "QAR",
      "subtotal": 99.98,
      "total": 99.98,
      "total_paid": 0,
      "total_due": 99.98,
      "tax": 0,
      "discount": 0,
      "shipping_price": 0,
      "shipping_tax": 0,
      "shipping_refund": 0,
      "attachments": null,
      "exchange_rate": {
        "rate": 0,
        "order_currency": "",
        "store_currency": ""
      },
      "additional_charges": [
        {
          "cost": 0,
          "type": "shipment_fee",
          "is_applied": true,
          "tax_amount": 0,
          "tax_inclusive": false,
          "tax_percentage": 0,
          "discount_amount": 0,
          "cost_without_tax": 0
        }
      ],
      "shipping_tax_inclusive": false,
      "sub_total_tax_inclusive": false,
      "shipping_discount_inclusive": false,
      "sub_total_discount_inclusive": false
    },
    "shipment": {
      "cod_amount": 0,
      "delivery_status": "pending",
      "shipping_account": { "id": "", "name": "" },
      "courier_partner": { "id": 0, "name": "", "tag": "", "logo": "" }
    },
    "sales_channel": {
      "tag": "shopify",
      "name": "Shopify",
      "category": "SalesChannel",
      "logo_url": ""
    },
    "slot": {},
    "driver_details": {},
    "external_fields": null,
    "expected_delivery_epoch": 0,
    "cancel_order_after_seconds": 0
  }
}

Order Event — order.update.event

Sent on status changes. Check data.status_code for the current status. See the status reference table below.

{
  "event_name": "order.update.event",
  "data": {
    "id": "6a042dc06ae04193e309e70e",
    "order_id": "ORD-20260513-002",
    "order_alias": "#1002",
    "status_code": "packed",
    "type": "b2c",
    "source": "sales_channel",
    "seller_code": "SELLER_A",
    "seller": {
      "code": "SELLER_A",
      "name": "My Store"
    },
    "hub_code": "HUB-QA-01",
    "total": 3,
    "payment_method": "postpaid",
    "shipment_type": "omniful_generated",
    "delivery_type": "normal_delivery",
    "require_shipping": true,
    "order_created_at": "2026-05-13T07:29:56Z",
    "updated_at": "2026-05-13T09:39:23.346741204Z",
    "store_name": "My Store - Qatar",
    "customer": {
      "first_name": "Ahmed",
      "last_name": "Al-Rashid",
      "email": "ahmed@example.com",
      "mobile": "+974-55001234",
      "mobile_code": "+974"
    },
    "shipping_address": {
      "first_name": "Ahmed",
      "last_name": "Al-Rashid",
      "phone": "+974-55001234",
      "address1": "Building 5, Street 10",
      "address2": "",
      "city": "Doha",
      "state": "Ad Dawhah",
      "state_code": "QA-DA",
      "country": "Qatar",
      "country_code": "QA",
      "zip": "12345",
      "latitude": 25.2854,
      "longitude": 51.531,
      "display_city": "",
      "country_calling_code": "+974",
      "national_address_code": ""
    },
    "billing_address": {
      "first_name": "Ahmed",
      "last_name": "Al-Rashid",
      "phone": "+974-55001234",
      "address1": "Building 5, Street 10",
      "address2": "",
      "city": "Doha",
      "state": "Ad Dawhah",
      "state_code": "QA-DA",
      "country": "Qatar",
      "country_code": "QA",
      "zip": "12345",
      "latitude": 25.2854,
      "longitude": 51.531,
      "display_city": "",
      "country_calling_code": "+974",
      "national_address_code": ""
    },
    "order_items": [
      {
        "sku_code": "SKU-001",
        "sku_id": "2617",
        "hs_code": "",
        "quantity": 1,
        "picked_quantity": 1,
        "packed_quantity": 1,
        "unit_price": 49.99,
        "selling_price": 0,
        "display_price": 0,
        "subtotal": 0,
        "total": 49.99,
        "discount": 0,
        "tax": 0,
        "tax_percent": 0,
        "tax_inclusive": false,
        "is_substituted": false,
        "item_barcodes": [],
        "serialised_sku_codes": [],
        "sales_channel_order_item_id": "25099",
        "substitute_seller_sku_codes": []
      },
      {
        "sku_code": "SKU-002",
        "sku_id": "5663",
        "hs_code": "",
        "quantity": 1,
        "picked_quantity": 1,
        "packed_quantity": 1,
        "unit_price": 29.99,
        "selling_price": 0,
        "display_price": 0,
        "subtotal": 0,
        "total": 29.99,
        "discount": 0,
        "tax": 0,
        "tax_percent": 0,
        "tax_inclusive": false,
        "is_substituted": false,
        "item_barcodes": [],
        "serialised_sku_codes": [],
        "sales_channel_order_item_id": "25100",
        "substitute_seller_sku_codes": []
      }
    ],
    "invoice": {
      "currency": "QAR",
      "subtotal": 79.98,
      "total": 79.98,
      "total_paid": 0,
      "total_due": 79.98,
      "tax": 0,
      "discount": 0,
      "payment_mode": "cashondelivery",
      "shipping_price": 0,
      "shipping_tax": 0,
      "shipping_refund": 0,
      "attachments": null,
      "exchange_rate": {
        "rate": 0,
        "order_currency": "",
        "store_currency": ""
      },
      "additional_charges": [],
      "shipping_tax_inclusive": false,
      "sub_total_tax_inclusive": false,
      "shipping_discount_inclusive": false,
      "sub_total_discount_inclusive": false
    },
    "shipment": {
      "cod_amount": 0,
      "delivery_status": "",
      "shipping_account": { "id": "", "name": "" },
      "courier_partner": { "id": 0, "name": "", "tag": "", "logo": "" }
    },
    "sales_channel": {
      "tag": "magento-2",
      "name": "Magento 2",
      "category": "SalesChannel",
      "logo_url": ""
    },
    "slot": {},
    "driver_details": {},
    "external_fields": null,
    "expected_delivery_epoch": 0,
    "cancel_order_after_seconds": 0
  }
}

Shipment Event — order.shipment.event (shipped)

Sent when an order is assigned to a driver for delivery. Check data.status_code for 'shipped'. The order status is updated before the payload is sent.

{
  "event_name": "order.shipment.event",
  "data": {
    "id": "69d79a1dfd569f3239412d3e",
    "order_id": "ORD-20260513-001",
    "order_alias": "#1001",
    "status_code": "shipped",
    "display_status": "Shipped",
    "type": "B2C",
    "source": "Sales Channel",
    "seller_code": "SELLER_A",
    "hub_code": "HUB-QA-01",
    "store_name": "My Store",
    "total": 150,
    "payment_method": "Prepaid",
    "shipment_type": "omniful_generated",
    "delivery_type": "normal_delivery",
    "require_shipping": true,
    "order_created_at": "2026-05-13T10:30:00Z",
    "is_cash_on_delivery": false,
    "customer": {
      "first_name": "Ahmed",
      "last_name": "Al-Rashid",
      "mobile": "+974-55001234",
      "mobile_code": "+974",
      "country_code": "",
      "country": "",
      "country_calling_code": ""
    },
    "shipping_address": {
      "first_name": "Ahmed",
      "last_name": "Al-Rashid",
      "phone": "+974-55001234",
      "address1": "Building 5, Street 10",
      "address2": "",
      "city": "Doha",
      "state": "Ad Dawhah",
      "country": "Qatar",
      "country_code": "QA",
      "zip": "12345",
      "latitude": 25.2854,
      "longitude": 51.531,
      "state_code": "QA-DA",
      "country_calling_code": "+974"
    },
    "billing_address": {
      "first_name": "Ahmed",
      "last_name": "Al-Rashid",
      "phone": "+974-55001234",
      "address1": "Building 5, Street 10",
      "address2": "",
      "city": "Doha",
      "state": "Ad Dawhah",
      "country": "Qatar",
      "country_code": "QA",
      "zip": "12345",
      "latitude": 25.2854,
      "longitude": 51.531,
      "state_code": "QA-DA",
      "country_calling_code": "+974"
    },
    "order_items": [
      {
        "sku_code": "SKU-001",
        "quantity": 1,
        "picked_quantity": 1,
        "packed_quantity": 1,
        "unit_price": 150,
        "selling_price": 150,
        "total": 150,
        "discount": 0,
        "tax": 0,
        "tax_percent": 0,
        "tax_inclusive": false,
        "is_substituted": false
      }
    ],
    "invoice": {
      "currency": "QAR",
      "subtotal": 150,
      "total": 150,
      "total_paid": 150,
      "total_due": 0,
      "tax": 0,
      "discount": 0,
      "payment_mode": "other",
      "shipping_price": 0,
      "shipping_tax": 0,
      "shipping_refund": 0,
      "additional_charges": [],
      "attachments": null,
      "shipping_tax_inclusive": false,
      "sub_total_tax_inclusive": false,
      "shipping_discount_inclusive": false,
      "sub_total_discount_inclusive": false
    },
    "shipment": {
      "awb_number": "8oGkkRTCSmJVFDbMOdjlFPLZ",
      "tracking_url": "https://portal.nbox.qa/track/8oGkkRTCSmJVFDbMOdjlFPLZ",
      "order_shipped_at": "2026-05-19T13:28:40.004Z",
      "shipment_created_at": "2026-05-19T13:07:12.749Z",
      "delivery_status": "ready_to_ship",
      "shipping_partner_name": "NBOX",
      "shipping_partner_tag": "nbox",
      "shipping_company": "Standard Delivery",
      "shipping_account": { "id": 0, "name": "NBOX Shipping" },
      "courier_partner": {
        "id": 0,
        "name": "NBOX",
        "tag": "nbox",
        "logo": "https://..."
      }
    },
    "slot": {},
    "driver_details": {},
    "external_fields": null,
    "expected_delivery_epoch": 0,
    "cancel_order_after_seconds": 0
  }
}

Shipment Event — order.shipment.event (delivered)

Sent when an order is delivered. Check data.status_code for 'delivered'. The shipment object includes AWB, tracking URL, and delivery timestamps.

{
  "event_name": "order.shipment.event",
  "data": {
    "id": "6a0326bf6ae04193e3067468",
    "order_id": "ORD-20260512-003",
    "order_alias": "#1003",
    "status_code": "delivered",
    "type": "b2c",
    "source": "sales_channel",
    "seller_code": "SELLER_A",
    "seller": {
      "code": "SELLER_A",
      "name": "My Store"
    },
    "hub_code": "HUB-QA-01",
    "total": 2,
    "payment_method": "prepaid",
    "shipment_type": "omniful_generated",
    "delivery_type": "normal_delivery",
    "require_shipping": true,
    "order_created_at": "2026-05-12T13:10:20Z",
    "updated_at": "2026-05-13T09:09:48.613Z",
    "store_name": "My Store - Qatar",
    "labels": ["Product_Personalizer"],
    "customer": {
      "first_name": "Ahmed",
      "last_name": "Al-Rashid",
      "email": "ahmed@example.com",
      "mobile": "+974-55001234",
      "mobile_code": "+974"
    },
    "shipping_address": {
      "first_name": "Ahmed",
      "last_name": "Al-Rashid",
      "phone": "+974-55001234",
      "address1": "Building 5, Street 10",
      "address2": "Apartment 3",
      "city": "Doha",
      "state": "Ad Dawhah",
      "state_code": "QA-DA",
      "country": "Qatar",
      "country_code": "QA",
      "zip": "12345",
      "latitude": 25.2854,
      "longitude": 51.531,
      "display_city": "",
      "country_calling_code": "+974",
      "national_address_code": ""
    },
    "billing_address": {
      "first_name": "Ahmed",
      "last_name": "Al-Rashid",
      "phone": "+974-55001234",
      "address1": "Building 5, Street 10",
      "address2": "Apartment 3",
      "city": "Doha",
      "state": "Ad Dawhah",
      "state_code": "QA-DA",
      "country": "Qatar",
      "country_code": "QA",
      "zip": "12345",
      "latitude": 25.2854,
      "longitude": 51.531,
      "display_city": "",
      "country_calling_code": "+974",
      "national_address_code": ""
    },
    "order_items": [
      {
        "sku_code": "SKU-001",
        "sku_id": "46896455811239",
        "hs_code": "",
        "quantity": 1,
        "picked_quantity": 1,
        "packed_quantity": 1,
        "unit_price": 129,
        "selling_price": 129,
        "display_price": 0,
        "subtotal": 0,
        "total": 129,
        "discount": 0,
        "tax": 0,
        "tax_percent": 0,
        "tax_inclusive": false,
        "is_substituted": false,
        "item_barcodes": [],
        "serialised_sku_codes": [],
        "sales_channel_order_item_id": "16255342674087",
        "substitute_seller_sku_codes": []
      },
      {
        "sku_code": "SKU-002",
        "sku_id": "46896451256487",
        "hs_code": "",
        "quantity": 1,
        "picked_quantity": 1,
        "packed_quantity": 1,
        "unit_price": 24,
        "selling_price": 24,
        "display_price": 0,
        "subtotal": 0,
        "total": 24,
        "discount": 0,
        "tax": 0,
        "tax_percent": 0,
        "tax_inclusive": false,
        "is_substituted": false,
        "item_barcodes": [],
        "serialised_sku_codes": [],
        "sales_channel_order_item_id": "16255342706855",
        "substitute_seller_sku_codes": []
      }
    ],
    "invoice": {
      "currency": "QAR",
      "subtotal": 153,
      "total": 153,
      "total_paid": 153,
      "total_due": 0,
      "tax": 0,
      "discount": 0,
      "payment_mode": "other",
      "shipping_price": 0,
      "shipping_tax": 0,
      "shipping_refund": 0,
      "attachments": null,
      "exchange_rate": {
        "rate": 0,
        "order_currency": "",
        "store_currency": ""
      },
      "additional_charges": [],
      "shipping_tax_inclusive": false,
      "sub_total_tax_inclusive": false,
      "shipping_discount_inclusive": true,
      "sub_total_discount_inclusive": true
    },
    "shipment": {
      "awb_number": "88QeVKPEBc4TvCN9hRMdQmh7",
      "cod_amount": 0,
      "tracking_url": "https://portal.nbox.qa/track/88QeVKPEBc4TvCN9hRMdQmh7",
      "courier_partner": {
        "id": 0,
        "tag": "nbox",
        "logo": "https://...",
        "name": "NBOX"
      },
      "delivery_status": "",
      "order_shipped_at": "2026-05-12T18:30:00Z",
      "order_delivered_at": "2026-05-13T09:09:48.613Z",
      "shipment_created_at": "2026-05-12T18:26:50.598Z",
      "shipping_account": {
        "id": "a39e76f6-5313-48fa-93e8-9ac5687450e2",
        "name": "NBOX Shipping"
      },
      "shipping_partner_tag": "nbox",
      "shipping_partner_name": "NBOX",
      "shipping_partner_status": "ready_to_ship"
    },
    "sales_channel": {
      "tag": "shopify",
      "name": "Shopify",
      "category": "SalesChannel",
      "logo_url": ""
    },
    "slot": {},
    "driver_details": {},
    "external_fields": null,
    "expected_delivery_epoch": 0,
    "cancel_order_after_seconds": 0
  }
}

Return Request Event — return.request.create.event

Sent when a return request is submitted. This is Phase 1 — before a return order is created.

{
  "event_name": "return.request.create.event",
  "data": {
    "return_request_number": "RR-13052026-ABCDE",
    "type": "customer_return",
    "return_request_status": "new",
    "order_id": "8012345678901",
    "seller_code": "SELLER_A",
    "hub_code": "HUB-QA-01",
    "order_items": [
      { "sku_code": "SKU-001", "return_quantity": 2 },
      { "sku_code": "SKU-002", "return_quantity": 1 },
      { "sku_code": "SKU-003", "return_quantity": 1 }
    ]
  }
}

Return Request Event — return.request.approve.event

Sent when a return request is approved. The request is now ready for a return order to be created.

{
  "event_name": "return.request.approve.event",
  "data": {
    "return_request_number": "RR-10052026-FGHIJ",
    "type": "customer_return",
    "return_request_status": "approved",
    "order_id": "7890123456789",
    "seller_code": "SELLER_B",
    "hub_code": "HUB-RY-02",
    "order_items": [
      { "sku_code": "WDG-PRO-BLK", "return_quantity": 1 },
      { "sku_code": "WDG-CASE-CLR", "return_quantity": 1 }
    ]
  }
}

Return Order Event — return_order.create.event

Sent when a return order is created in the warehouse.

{
  "event_name": "return_order.create.event",
  "data": {
    "id": "69cb6990a81f775a8a0e5bd5",
    "return_order_id": "RO-13052026-ABCDE",
    "order_id": "693e4b27d0bad2be284a5fee",
    "order_reference_id": "ORD-20260510-042",
    "type": "customer_return",
    "source": "manual",
    "hub_code": "HUB-QA-01",
    "seller_name": "My Store",
    "seller_code": "SELLER_A",
    "total": 1,
    "status": "Initiated",
    "refund_status": "pending",
    "oms_qc_status": "pending",
    "payment_method": "prepaid",
    "total_return_quantity": 1,
    "total_sku_count": 1,
    "delivered_quantity": 2,
    "total_passed_quantity": 0,
    "customer": {
      "first_name": "Ahmed",
      "last_name": "Al-Rashid",
      "email": "ahmed@example.com",
      "mobile": "+974-55001234",
      "mobile_code": "+974"
    },
    "pickup_address": {
      "first_name": "",
      "last_name": "",
      "phone": "",
      "email": "",
      "address1": "",
      "address2": "",
      "area": "",
      "city": "Doha",
      "state": "",
      "state_code": "",
      "country": "Qatar",
      "country_code": "QA",
      "zip": "",
      "latitude": 25.2854,
      "longitude": 51.531,
      "national_address_code": ""
    },
    "order_items": [
      {
        "seller_sku_code": "SKU-001",
        "seller_sku": {
          "seller_sku_code": "SKU-001",
          "name": "Product Name",
          "type": "simple",
          "barcodes": ["6273000324351"],
          "description": "",
          "cost": 0,
          "cutoff_price": 0,
          "retail_price": 0,
          "handling_type": "",
          "is_perishable": false,
          "country_of_origin": ""
        },
        "return_quantity": 1,
        "delivered_quantity": 2,
        "refunded_quantity": 0,
        "returned_quantity": 0,
        "pass_quantity": 0,
        "unit_price": 49.99,
        "selling_price": 49.99,
        "total": 49.99,
        "discount": 0,
        "tax": 0,
        "tax_percent": 0,
        "is_weighted": false,
        "return_reason": "Damaged",
        "return_reasons": ["Damaged"],
        "return_weight": { "uom": "ea", "value": 1 },
        "display_return_weight": "",
        "item_barcodes": null
      }
    ],
    "invoice": {
      "currency": "QAR",
      "subtotal": 49.99,
      "total": 49.99,
      "total_paid": 0,
      "total_due": 49.99,
      "tax": 0,
      "discount": 0,
      "shipping_price": 0,
      "shipping_tax": 0,
      "shipping_refund": 0,
      "attachments": null,
      "exchange_rate": {
        "rate": 0,
        "order_currency": "",
        "store_currency": ""
      },
      "additional_charges": null,
      "shipping_tax_inclusive": false,
      "sub_total_tax_inclusive": false,
      "shipping_discount_inclusive": false,
      "sub_total_discount_inclusive": false
    },
    "shipment": {
      "cod_amount": 0,
      "delivery_status": "",
      "courier_partner": { "id": 0, "tag": "", "logo": "", "name": "" },
      "shipping_account": { "id": "", "name": "" },
      "order_shipped_at": "0001-01-01T00:00:00Z",
      "order_delivered_at": "0001-01-01T00:00:00Z",
      "shipment_created_at": "0001-01-01T00:00:00Z"
    },
    "order_created_at": "2026-05-10T08:00:00Z",
    "order_delivered_at": "2026-05-12T14:30:00Z"
  }
}

Return Order Event — return_order.qc.event

Sent when QC inspection is completed. Check data.oms_qc_status for the result and data.pass_quantity on each item.

{
  "event_name": "return_order.qc.event",
  "data": {
    "id": "69cb6990a81f775a8a0e5bd5",
    "return_order_id": "RO-13052026-ABCDE",
    "order_id": "693e4b27d0bad2be284a5fee",
    "order_reference_id": "ORD-20260510-042",
    "type": "customer_return",
    "source": "manual",
    "hub_code": "HUB-QA-01",
    "seller_name": "My Store",
    "seller_code": "SELLER_A",
    "total": 1,
    "status": "qc_processed",
    "refund_status": "pending",
    "oms_qc_status": "completed",
    "payment_method": "prepaid",
    "total_return_quantity": 1,
    "total_sku_count": 1,
    "delivered_quantity": 2,
    "total_passed_quantity": 1,
    "customer": {
      "first_name": "Ahmed",
      "last_name": "Al-Rashid",
      "email": "ahmed@example.com",
      "mobile": "+974-55001234",
      "mobile_code": "+974"
    },
    "pickup_address": {
      "first_name": "",
      "last_name": "",
      "phone": "",
      "email": "",
      "address1": "",
      "address2": "",
      "area": "",
      "city": "Doha",
      "state": "",
      "state_code": "",
      "country": "Qatar",
      "country_code": "QA",
      "zip": "",
      "latitude": 25.2854,
      "longitude": 51.531,
      "national_address_code": ""
    },
    "order_items": [
      {
        "seller_sku_code": "SKU-001",
        "seller_sku": {
          "seller_sku_code": "SKU-001",
          "name": "Product Name",
          "type": "simple",
          "barcodes": ["6273000324351"],
          "description": "",
          "cost": 0,
          "cutoff_price": 0,
          "retail_price": 0,
          "handling_type": "",
          "is_perishable": false,
          "country_of_origin": ""
        },
        "return_quantity": 1,
        "delivered_quantity": 2,
        "refunded_quantity": 0,
        "returned_quantity": 0,
        "pass_quantity": 1,
        "unit_price": 49.99,
        "selling_price": 49.99,
        "total": 49.99,
        "discount": 0,
        "tax": 0,
        "tax_percent": 0,
        "is_weighted": false,
        "return_reason": "Damaged",
        "return_reasons": ["Damaged"],
        "return_weight": { "uom": "ea", "value": 1 },
        "display_return_weight": "",
        "item_barcodes": null
      }
    ],
    "invoice": {
      "currency": "QAR",
      "subtotal": 49.99,
      "total": 49.99,
      "total_paid": 0,
      "total_due": 0,
      "tax": 0,
      "discount": 0,
      "shipping_price": 0,
      "shipping_tax": 0,
      "shipping_refund": 0,
      "attachments": null,
      "exchange_rate": {
        "rate": 0,
        "order_currency": "",
        "store_currency": ""
      },
      "additional_charges": null,
      "shipping_tax_inclusive": false,
      "sub_total_tax_inclusive": false,
      "shipping_discount_inclusive": false,
      "sub_total_discount_inclusive": false
    },
    "shipment": {
      "cod_amount": 0,
      "delivery_status": "",
      "courier_partner": { "id": 0, "tag": "", "logo": "", "name": "" },
      "shipping_account": { "id": "", "name": "" },
      "order_shipped_at": "0001-01-01T00:00:00Z",
      "order_delivered_at": "0001-01-01T00:00:00Z",
      "shipment_created_at": "0001-01-01T00:00:00Z"
    },
    "order_created_at": "2026-05-10T08:00:00Z",
    "order_delivered_at": "2026-05-12T14:30:00Z"
  }
}

Retry & Error Handling

Delivery Attempts

Max attempts	3 (with exponential backoff: ~1s, ~2s, ~4s)
Timeout	10 seconds per attempt
Retryable codes	`408` `429` `500` `502` `503` `504`

429 Rate Limit Handling

If your endpoint returns 429, the event is not counted as a failure. Instead, it is re-enqueued with increasing delays (5s → 10s → ... up to 5 min). Respects Retry-After header. After 10 re-enqueue attempts, the event is dropped and you receive an alert email.

Auto-Disable

After 10 consecutive failures, the webhook is automatically disabled and you receive an alert email. The counter resets on any successful delivery.

Your Endpoint Requirements

Respond within 10 seconds with any 2xx status
Use X-NBOX-Delivery-ID to deduplicate — the same event may arrive more than once
HTTPS is recommended for production