> For the complete documentation index, see [llms.txt](https://eshop.gitbook.io/eshopbox-developers/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://eshop.gitbook.io/eshopbox-developers/order/shipper-integration-wrapper-api/registering-webhook-for-tracking-shipment.md).

# Registering webhook for tracking shipment

### 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

<table data-header-hidden><thead><tr><th width="194.33331298828125"></th><th width="96.6666259765625"></th><th width="193.6666259765625"></th><th></th></tr></thead><tbody><tr><td>Name</td><td>Required</td><td>Remarks</td><td>Type</td></tr><tr><td>resource</td><td>Yes</td><td>Target resource for the webhook channel_inventory, shipment and returnShipment.</td><td>String</td></tr><tr><td>eventType</td><td>Yes</td><td>Type of event action (e.g., POST, PUT).</td><td>String</td></tr><tr><td>eventSubType</td><td>Yes</td><td>Sub-category of the event (e.g., updated, created).</td><td>String</td></tr><tr><td>version</td><td>Yes</td><td>API or event version (e.g., v1).</td><td>String</td></tr><tr><td>externalChannelID</td><td>Optional</td><td>Identifier for your external sales channel (useful for multi-channel setups).</td><td>String</td></tr><tr><td>webhookUrl</td><td>Yes</td><td>Your application’s endpoint URL where the webhook payload will be delivered.</td><td>String (URL)</td></tr><tr><td>webhookMethod</td><td>Yes</td><td>HTTP method Eshopbox will use to send the payload (usually POST).</td><td>String</td></tr><tr><td>webhookHeaders</td><td>Optional</td><td>Key-value pairs for custom headers (auth, API keys, etc.).</td><td>Object</td></tr><tr><td>webhookHeaders.x-api-key</td><td>Optional</td><td>API key used to authenticate webhook requests.</td><td>String</td></tr><tr><td>webhookHeadrs.sample-header-key</td><td>Optional</td><td>Bearer token or authorization credential used to validate requests.</td><td>String</td></tr><tr><td>webhookHeaders.authorization</td><td>Optional</td><td>Optional custom header that can be configured based on integration needs.</td><td>String</td></tr><tr><td>webhookHeaders.custom-header</td><td>Optional</td><td>Any additional custom header value.</td><td>String</td></tr><tr><td>webhookHeaders.content-type</td><td>Optional</td><td>Specifies the format of the webhook payload, typically application/json.</td><td>String</td></tr></tbody></table>

### Sample Payload to register your webhook

```json
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.&#x20;

#### Inventory Events

<table data-header-hidden><thead><tr><th width="94"></th><th width="131.3333740234375"></th><th width="102"></th><th width="80.6666259765625"></th><th></th></tr></thead><tbody><tr><td>Stage</td><td>Event Subtype</td><td>EventType</td><td>Version</td><td>Description</td></tr><tr><td>Inventory Update</td><td>Update</td><td>Post</td><td>v1</td><td>Triggered whenever there is an update to the product inventory</td></tr></tbody></table>

### Forward Shipment Events&#x20;

<table data-header-hidden><thead><tr><th width="149.99993896484375"></th><th width="159"></th><th width="117.6666259765625"></th><th width="92.33331298828125"></th><th></th></tr></thead><tbody><tr><td><strong>Workspace status</strong></td><td><strong>Event Subtype</strong></td><td><strong>EventType</strong></td><td><strong>Version</strong></td><td><strong>Description</strong></td></tr><tr><td>Processing</td><td>created</td><td>Put</td><td>v1</td><td>Shipment is created in the system.</td></tr><tr><td>Ready to Ship</td><td>packed</td><td>Put</td><td>v1</td><td>The order is packed and ready for dispatch.</td></tr><tr><td>Ready to Ship</td><td>ready_to_ship</td><td>Put</td><td>v1</td><td>Shipment is ready to be handed over to the courier partner.</td></tr><tr><td>On the way</td><td>picked_up</td><td>Put</td><td>v</td><td>The courier partner has picked up the shipment.</td></tr><tr><td>Ready to ship</td><td>out_for_pickup</td><td>Put</td><td>v1</td><td>Shipment is out for pickup.</td></tr><tr><td>Ready to Ship</td><td>pickup_failed</td><td>Put</td><td>v1</td><td>The courier partner failed to pick up the shipment.</td></tr><tr><td>On the way</td><td>intransit</td><td>Put</td><td>v1</td><td>The shipment is moving between courier hubs.</td></tr><tr><td>Out for Delivery</td><td>out_for_delivery</td><td>Put</td><td>v1</td><td>The courier partner is out to deliver the shipment to the customer.</td></tr><tr><td>Delivered</td><td>delivered</td><td>Put</td><td>v1</td><td>The shipment has been successfully delivered to the customer.</td></tr><tr><td>On the way</td><td>failed_delivery</td><td>Put</td><td>v1</td><td>Delivery attempt failed (e.g., customer not available).</td></tr><tr><td>Delivery cancelled</td><td>rto_created</td><td>Put</td><td>v1</td><td>Return to Origin initiated for the shipment.</td></tr><tr><td>Return on the way</td><td>rto_intransit</td><td>Put</td><td>v1</td><td>Shipment is in transit back to the origin warehouse.</td></tr><tr><td>Return on the way</td><td>rto_out_for_delivery</td><td>Put</td><td>v1</td><td>The shipment is out for delivery at the origin.</td></tr><tr><td>Return Delivered</td><td>rto_delivered</td><td>Put</td><td>v1</td><td>The returned shipment has been successfully delivered back to the origin.</td></tr><tr><td>Return on the way</td><td>rto_failed</td><td>Put</td><td>v1</td><td>Return to origin attempt failed.</td></tr><tr><td>On the way</td><td>shipment_delayed</td><td>Put</td><td>v1</td><td>The shipment has been delayed due to operational issues.</td></tr><tr><td>Handover done</td><td>dispatched</td><td>Put</td><td>v1</td><td>The shipment has been dispatched from the warehouse.</td></tr><tr><td>On the way</td><td>shipment_held</td><td>Put</td><td>v1</td><td>Shipment is temporarily on hold due to exceptions.</td></tr><tr><td>Processing</td><td>unhold</td><td>Put</td><td>v1</td><td>Shipment has been released from hold.</td></tr><tr><td>Return on the way</td><td>return_expected</td><td>Put</td><td>v1</td><td>Return from the customer is expected (usually post-NDR or return).</td></tr><tr><td>Cancelled </td><td>cancelled_order</td><td>Put</td><td>v1</td><td>The order has been cancelled.</td></tr><tr><td>On the way</td><td>ndr_resolution_submitted</td><td>Put</td><td>v1</td><td>Non-Delivery Report submitted for resolution.</td></tr><tr><td>Damaged</td><td>damage</td><td>Put</td><td>v1</td><td>Shipment is reported as damaged.</td></tr><tr><td>Lost</td><td>lost</td><td>Put</td><td>v1</td><td>Shipment is reported as lost in transit.</td></tr></tbody></table>

***

### Return Shipment Events

<table data-header-hidden><thead><tr><th></th><th width="193"></th><th width="102.66668701171875"></th><th width="79.33331298828125"></th><th></th></tr></thead><tbody><tr><td>Workspace Status</td><td>Event Subtype</td><td>EventType</td><td>Version</td><td>Description</td></tr><tr><td>Awaiting pickup</td><td>created</td><td>Put</td><td>v1</td><td>A return request is created by the customer.</td></tr><tr><td>Awaiting pickup</td><td>pickup_pending</td><td>Put</td><td>v1</td><td>Return pickup is scheduled but still pending.</td></tr><tr><td>Awaiting pickup</td><td>out_for_pickup</td><td>Put</td><td>v1</td><td>The courier partner is out to pick up the return shipment.</td></tr><tr><td>Awaiting pickup</td><td>pickup_cancelled</td><td>Post</td><td>v1</td><td>Return pickup has been cancelled by the courier or customer.</td></tr><tr><td>Awaiting pickup</td><td>pickup_failed</td><td>Put</td><td>v1</td><td>The courier partner failed to pick up the return shipment.</td></tr><tr><td>Return on the way</td><td>picked_up</td><td>Put</td><td>v1</td><td>Return shipment has been successfully picked up.</td></tr><tr><td>Return on the way</td><td>intransit</td><td>Put</td><td>v1</td><td>Return shipment is moving between courier hubs.</td></tr><tr><td>Return on the way</td><td>out_for_delivery</td><td>Put</td><td>v1</td><td>The courier partner is out to deliver the return shipment to the warehouse.</td></tr><tr><td></td><td>delivered</td><td>Put</td><td>v2</td><td>Return shipment delivered to the destination (customer or interim location).</td></tr><tr><td>Return Delivered</td><td>delivered_warehouse</td><td>Put</td><td>v2</td><td>Return shipment has been delivered to the warehouse.</td></tr><tr><td>Return on the way</td><td>failed_delivery</td><td>Put</td><td>v1</td><td>Return delivery attempt failed.</td></tr><tr><td>Restocked/Qurantined/Damanged/Lost</td><td>complete</td><td>Put</td><td>v1</td><td>Return process is successfully completed.</td></tr><tr><td>Cancelled Return</td><td>return_cancelled</td><td>Put</td><td>v1</td><td>Return request has been cancelled.</td></tr><tr><td>Awaiting pickup</td><td>approved</td><td>Put</td><td>v1</td><td>Return shipment has been approved after quality checks.</td></tr><tr><td>Lost</td><td>lost</td><td>Put</td><td>v1</td><td><p>Return shipment is reported as lost in transit.</p><p> </p></td></tr></tbody></table>

***

## Sample Webhook Payload&#x20;

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

### &#x20;**Inventory**:

```json
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:

```json
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:

```json
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"
}

```

<br>