Registering webhook for tracking shipment

The Webhook API delivers real-time notifications about inventory, fulfillment and return from Eshopbox.

Registering a Webhook

You can register your webhook using the Webhook API.

Registering the webhook URL with headers and body

Curl command for registering the webhook URL with headers: Curl: Post https://{accountSlug}.myeshopbox.com/api/v1/webhook

Headers

Name

Value

Content-Type

application/json

Authorization

Bearer XXXXX

ProxyHost

account slug

Body

Name

Required

Remarks

Type

resource

Yes

Target resource for the webhook channel_inventory, shipment and returnShipment.

String

eventType

Yes

Type of event action (e.g., POST, PUT).

String

eventSubType

Yes

Sub-category of the event (e.g., updated, created).

String

version

Yes

API or event version (e.g., v1).

String

externalChannelID

Optional

Identifier for your external sales channel (useful for multi-channel setups).

String

webhookUrl

Yes

Your application’s endpoint URL where the webhook payload will be delivered.

String (URL)

webhookMethod

Yes

HTTP method Eshopbox will use to send the payload (usually POST).

String

webhookHeaders

Optional

Key-value pairs for custom headers (auth, API keys, etc.).

Object

webhookHeaders.x-api-key

Optional

API key used to authenticate webhook requests.

String

webhookHeadrs.sample-header-key

Optional

Bearer token or authorization credential used to validate requests.

String

webhookHeaders.authorization

Optional

Optional custom header that can be configured based on integration needs.

String

webhookHeaders.custom-header

Optional

Any additional custom header value.

String

webhookHeaders.content-type

Optional

Specifies the format of the webhook payload, typically application/json.

String

Sample Payload to register your webhooko

curl --location ‘https://{accountSlug}.myeshopbox.com/api/v1/webhook’ \
--header ‘content-type: application/json’ \
--header ‘Authorization: Bearer XXXXX \
--header ‘proxyHost: eshop’ \
--data ‘ {
    "resource": "channel_inventory",
    "eventType": "POST",
    "eventSubType": "updated",
    "version": "v1",
    "externalChannelID": "TEST",
    "webhookUrl": "https://webhook.testurl.com/fake-subscription-url2",
    "webhookMethod": "POST",
    "webhookHeaders": {
        "x-api-key": "test1234",
        "sample-header-key": "test875876",
        "authorization": "Bearer abcdef123456",
        "custom-header": "customValue",
        "content-type": "application/json"
    }
}’

Webhook API - Event Details and Status

Using this API, you can register your endpoint with Eshopbox to receive event notifications. Below are the details of supported resources, event types, event subtypes, and versions.

Inventory Events

Stage

Event Subtype

EventType

Version

Description

Inventory Update

Update

Post

v1

Triggered whenever there is an update to the product inventory

Forward Shipment Events

Stage

Event Subtype

EventType

Version

Description

Shipment Created

created

Put

v1

Shipment is created in the system.

Order Packed

packed

Put

v1

The order is packed and ready for dispatch.

Ready to Ship

ready_to_ship

Put

v1

Shipment is ready to be handed over to the courier partner.

Picked up

picked_up

Put

v

The courier partner has picked up the shipment.

Out for Pickup

out_for_pickup

Put

v1

Shipment is out for pickup.

Pickup Failed

pickup_failed

Put

v1

The courier partner failed to pick up the shipment.

In Transit

intransit

Put

v1

The shipment is moving between courier hubs.

Out for Delivery

out_for_delivery

Put

v1

The courier partner is out to deliver the shipment to the customer.

Delivered

delivered

Put

v1

The shipment has been successfully delivered to the customer.

Failed Delivery

failed_delivery

Put

v1

Delivery attempt failed (e.g., customer not available).

Return to Origin

rto_created

Put

v1

Return to Origin initiated for the shipment.

RTO In Transit

rto_intransit

Put

v1

Shipment is in transit back to the origin warehouse.

RTO Out for Delivery

rto_out_for_delivery

Put

v1

The shipment is out for delivery at the origin.

RTO Delivered

rto_delivered

Put

v1

The returned shipment has been successfully delivered back to the origin.

RTO Failed

rto_failed

Put

v1

Return to origin attempt failed.

Shipment Delayed

shipment_delayed

Put

v1

The shipment has been delayed due to operational issues.

Shipment Dispatched

dispatched

Put

v1

The shipment has been dispatched from the warehouse.

Shipment Held

shipment_held

Put

v1

Shipment is temporarily on hold due to exceptions.

Unhold

unhold

Put

v1

Shipment has been released from hold.

Return Expected

return_expected

Put

v1

Return from the customer is expected (usually post-NDR or return).

Cancelled Order

cancelled_order

Put

v1

The order has been cancelled.

NDR Submitted

ndr_resolution_submitted

Put

v1

Non-Delivery Report submitted for resolution.

Damage

damage

Put

v1

Shipment is reported as damaged.

Lost

lost

Put

v1

Shipment is reported as lost in transit.

Return Shipment Events

Stage

Event Subtype

EventType

Version

Description

Return Created

created

Put

v1

A return request is created by the customer.

Pickup Pending

pickup_pending

Put

v1

Return pickup is scheduled but still pending.

Out for Pickup

out_for_pickup

Put

v1

The courier partner is out to pick up the return shipment.

Pickup Cancelled

pickup_cancelled

Post

v1

Return pickup has been cancelled by the courier or customer.

Pickup Failed

pickup_failed

Put

v1

The courier partner failed to pick up the return shipment.

Picked Up

picked_up

Put

v1

Return shipment has been successfully picked up.

In Transit

intransit

Put

v1

Return shipment is moving between courier hubs.

Out for Delivery

out_for_delivery

Put

v1

The courier partner is out to deliver the return shipment to the warehouse.

Delivered

delivered

Put

v2

Return shipment delivered to the destination (customer or interim location).

Delivered to WH

delivered_warehouse

Put

v2

Return shipment has been delivered to the warehouse.

Failed Delivery

failed_delivery

Put

v1

Return delivery attempt failed.

Return Complete

complete

Put

v1

Return process is successfully completed.

Cancelled Return

return_cancelled

Put

v1

Return request has been cancelled.

Return Approved

approved

Put

v1

Return shipment has been approved after quality checks.

Return Lost

lost

Put

v1

Return shipment is reported as lost in transit.

Sample Webhook Payload

Webhook payloads are delivered as a POST request to your registered endpoint in JSON format.

Inventory:

curl --location --request POST 'Update' \
--header 'Content-Type: application/json' \
--data-raw '{
    "productId": "Test001",
    "parentId": "Eshopbox Test",
    "sellerSku": "",
    "sku": "Test",
    "variantId": "1600A01V03",
    "inventory": "36",
    "changeInStock": 0.0,
    "locationInventory": "0.0",
    "inventoryItemId": "1600A01V03"
}

Shipments:

curl --location --request POST 'shipment_created' \
--header 'Content-Type: application/json' \
--data-raw '{
    "customerOrderNumber": "TEST12AJY1",
    "orderSiteID": "",
    "vendorOrderNumber": "TEST12AJY1",
    "externalShipmentID": "TEST12AJY1-3439-3347",
    "externalWarehouseID": "Eshopboxdemo_LAZY02",
    "externalChannelID": "CH3439",
    "externalWmsChannelName": "SHOPIFY_ESHOPBOXDEMO_LAZY02_6259",
    "external_wms_channel_id": 6259.0,
    "channelLabel": "Shopify - Kapas Kraft 11",
    "integrationType": "7",
    "defaultWarehouseCode": "Eshopboxdemo_LAZY02",
    "facilityLabel": "Delhi Warehouse (LAZY02)",
    "flexStatus": "1",
    "facilityType": "auperator",
    "locationCode": "LAZY02",
    "orderDate": "2025-09-03 09:55:36",
    "portal_id": 27.0,
    "paymentType": "Prepaid",
    "expectedShipDate": "2025-09-04 12:00:00",
    "order_id": 6.1196917E7,
    "channel_id": 3439.0,
    "warehouse_id": 1496.0,
    "channel_account_id": 0.0,
    "account_id": 1215.0,
    "connectionId": 3381.0,
    "locationId": "75737301238",
    "region": "",
    "isMetro": "0",
    "isSpecialplace": "0",
    "invoiceNumber": "",
    "boxType": "UNKNOWN",
    "isPriorityShipment": "0",
    "isGift": "0",
    "invoice_url": "",
    "label_url": "",
    "labels": "",
    "shippingInfo": [],
    "boxAdditionalRecommendation": [],
    "dimension_length": 0.0,
    "dimension_width": 0.0,
    "dimension_height": 0.0,
    "weight": 0.0,
    "chargeableWeight": "0",
    "trackingID": "",
    "trackingDomain": "",
    "packageID": "",
    "barcode": "",
    "barcodeType": "no_inventory",
    "taxAmount": 0.0,
    "shipChargeAmount": 6.67,
    "courierName": "Delhivery",
    "cp_id": 4.0,
    "created_at": "2025-09-03 15:25:41",
    "updated_at": "2025-09-03 15:25:41",
    "status": "created",
    "remarks": "",
    "warehousePincode": "122015",
    "thirdPartyShipping": false,
    "customerName": "John doe",
    "customerContactNumber": "9999999999",
    "email": "johndoe@test.com",
    "channelSlug": "eshopboxdemo3439",
    "status_updated_at": "2025-09-03 15:25:41",
    "status_log": {
        "created": "2025-09-03 15:25:41"
    },
    "status_log_first_occurrence": {
        "created": "2025-09-03 15:25:41"
    },
    "status_log_count": {
        "created": 1.0
    },
    "status_log_id": "260774678",
    "orderExternalCreatedAt": "2025-09-03 15:25:39",
    "riskScoreReasons": "",
    "weightProtectionShieldFlag": false,
    "pincodeServiceableRemarks": "",
    "orderAdditionalInfo": "",
    "shippingAddress": {
        "customerName": "John doe",
        "addressLine1": "64 Sector 18, Hsidc Maruti Indl Area",
        "addressLine2": "",
        "city": "Delhi",
        "state": "Delhi",
        "postalCode": "110001",
        "countryCode": "IN",
        "countryName": "IN",
        "contactPhone": "8793260144",
        "email": "johndoe@test.com"
    },
    "billingAddress": {
        "customerName": "John doe",
        "email": "johndoe@test.com",
        "contactPhone": "8793260144"
    },
    "warehouseAddress": {
        "addressLine1": "68p sector 22, gurgaon ke piche",
        "addressLine2": "",
        "city": "Gurgaon",
        "state": "Haryana",
        "postalCode": "122015",
        "gstin": ""
    },
    "eshopboxCourier": true,
    "courier_account": "ESB_Delhivery_60KG",
    "shippingMode": "standard",
    "portalUrl": "https://encrypted-tbn0.gstatic.com/images?q\u003dtbn:ANd9GcSMTVs0QAk8zn1HybVnMWMKrX_FcoDdOjYLvigHG38Y6GSpxl2m1xHAV7q1EUyEgn-kwpk\u0026usqp\u003dCAU",
    "id": 2.9421797E7,
    "orderTotal": 340.0,
    "subTotal": 333.33,
    "isCOD": "0",
    "track_payload": [],
    "itemsWeightProtectionShieldFlag": false,
    "items": [
        {
            "order_item_id": 4.7654007E7,
            "lineItemSequenceNumber": 1.0,
            "orderItemID": "TEST12AJY1-47654007",
            "itemID": "30JQZ3I59FC",
            "sku": "FCN2X3I59FP",
            "asin": "",
            "productName": "3 OVARES JACKET",
            "quantity": 1.0,
            "orderItemCreatedAt": "2025-09-03 15:25:39",
            "customerPrice": 0.0,
            "lineItemTotal": 333.33,
            "invoiceTotal": 340.0,
            "cashOnDeliveryCharges": 0.0,
            "discount": -333.33,
            "taxRate": 0.0,
            "taxAmount": 0.0,
            "inventoryItemCode": "",
            "giftMessage": "",
            "isGift": "0",
            "giftLabelContent": "",
            "lineItemOrderStatus": "",
            "orderItemIDs": [
                "TEST12AJY1-47654007"
            ],
            "productAdditionalInfo": {
                "productDetails": {
                    "hsnCode": "",
                    "description": "3 OVARES JACKET",
                    "mrp": 1000.0,
                    "type": "BASE",
                    "accountSlug": "eshopboxdemo",
                    "sku": "30JQZ3I59FC",
                    "esin": "FCN2X3I59FP",
                    "status": "DRAFT",
                    "weightUnit": "g"
                }
            },
            "shippingCharges": 6.67,
            "isVirtualKit": "0",
            "component": [],
            "onhold": "0",
            "cancellationAdditionalReason": "",
            "cancellationReason": "",
            "customerOrderItemID": "",
            "recallBlockedInventoryUsed": ""
        }
}'

Return Shipment:

curl --location --request POST 'return_created' \
--header 'Content-Type: application/json' \
--data-raw '{
  "customerContactNumber": "9999999999",
  "vendorOrderNumber": "TEST12AJY1",
  "expectedPickUpDate": "2025-06-14",
  "created_at": "2025-06-13 18:40:46",
  "customerReturnNumber": "R174982024396544887495",
  "customerOrderNumber": "TEST12AJY1",
  "courierName": "Delhivery Reverse",
  "isCOD": "1",
  "returnReason": "Damaged item received",
  "channelSlug": "eshopboxdemo3439",
  "returnShipmentId": "4789234",
  "email": "johndoe@test.com",
  "isReturnFlag": "1",
  "channelId": "3205",
  "refundAmount": 1959.0,
  "latest_status": "approved",
  "externalChannelID": "CH3439",
  "customerName": "John doe",
  "reversePickUpCreatedDate": "",
  "pickupAddress": {
    "pickup_postalCode": "110001",
    "pickup_customerName": "John doe",
    "pickup_addressLine1": "64 Sector 18, Hsidc Maruti Indl Area",
    "pickup_addressLine2": "",
    "pickup_city": "Delhi",
    "pickup_state": "Delhi"
  },
  "shippingAddress": {
    "shipping_customerName": "John doe",
    "shipping_state": "Delhi",
    "shipping_city": "Delhi",
    "shipping_addressLine1": "64 Sector 18, Hsidc Maruti Indl Area",
    "shipping_postalCode": "110001"
  },
  "pickupDate": "2025-06-14",
  "status_log": {
    "approved": "2025-06-13 18:40:46",
    "created": "2025-06-13 18:40:44"
  },
  "billingAddress": {
    "billing_city": "Delhi",
    "billing_customerName": "Pankaj Parmar",
    "billing_state": "Delhi",
    "billing_postalCode": "110001",
    "billing_addressLine1": "64 Sector 18, Hsidc Maruti Indl Area"
  },
  "locationCode": "XMUM",
  "items": [
    {
      "productImageUrl": "https://cdn.staticans.com/image/tr:e-sharpen-01,h-1280,w-1500,cm-pad_resize/data/13jun2024/F016800536_1.png",
      "productAdditionalInfo": {
        "productDetails": {
          "unitPrice": 1960.0,
          "hsnCode": "84248990",
          "dimensionHeight": 7.0,
          "dimensionLength": 26.8,
          "dimensionUnit": "cm",
          "description": "Trigger 360 Gun",
          "weight": 630.0,
          "weight_dimension_status": "unverified",
          "mrp": 2499.0,
          "dimensionWidth": 22.0,
          "type": "BASE",
          "taxCode": "ESBGST5",
          "verticalName": "Home Improvement",
          "imageUrl": "https://cdn.staticans.com/image/tr:e-sharpen-01,h-1280,w-1500,cm-pad_resize/data/13jun2024/F016800536_1.png",
          "accountSlug": "eshopboxdemo3439",
          "sku": "F016800536",
          "esin": "36HXS3HT9UF",
          "brand": "",
          "additionalNames": {
            "ean": "3165140926614"
          },
          "groupCode": "DIY",
          "status": "ACTIVE",
          "weightUnit": "g"
        }
      },
      "quantity": 1.0,
      "customerOrderItemID": "f4c66466-9a61-45e8-af7c-fda8d8e3cf74",
      "shippingCharges": "0.0",
      "orderItemID": "DIINQ1000260-44887495",
      "lineItemTotal": "1959.0",
      "productName": "360° Gun",
      "itemID": "F016800536",
      "returnFlag": "1",
      "returnRequestedDate": "2025-06-13 18:40:44",
      "returnReason": "Damaged item received",
      "productUrl": "360-gun-F016800536",
      "sku": "36HXS3HT9UF"
    }
  ],
  "order_id": 60113678.0,
  "trackingID": "2098313447986",
  "status": "approved"
}

PreviousGet Tracking Details via pollingNextPayout

Last updated

Was this helpful?