# 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="161.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="116"></th><th width="144"></th><th width="100.6666259765625"></th><th width="83.33331298828125"></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>Shipment Created</td><td>created</td><td>Put</td><td>v1</td><td>Shipment is created in the system.</td></tr><tr><td>Order Packed</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>Picked up</td><td>picked_up</td><td>Put</td><td>v</td><td>The courier partner has picked up the shipment.</td></tr><tr><td>Out for Pickup</td><td>out_for_pickup</td><td>Put</td><td>v1</td><td>Shipment is out for pickup.</td></tr><tr><td>Pickup Failed</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>In Transit</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>Failed Delivery</td><td>failed_delivery</td><td>Put</td><td>v1</td><td>Delivery attempt failed (e.g., customer not available).</td></tr><tr><td>Return to Origin</td><td>rto_created</td><td>Put</td><td>v1</td><td>Return to Origin initiated for the shipment.</td></tr><tr><td>RTO In Transit</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>RTO Out for Delivery</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>RTO 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>RTO Failed</td><td>rto_failed</td><td>Put</td><td>v1</td><td>Return to origin attempt failed.</td></tr><tr><td>Shipment Delayed</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>Shipment Dispatched</td><td>dispatched</td><td>Put</td><td>v1</td><td>The shipment has been dispatched from the warehouse.</td></tr><tr><td>Shipment Held</td><td>shipment_held</td><td>Put</td><td>v1</td><td>Shipment is temporarily on hold due to exceptions.</td></tr><tr><td>Unhold</td><td>unhold</td><td>Put</td><td>v1</td><td>Shipment has been released from hold.</td></tr><tr><td>Return Expected</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 Order</td><td>cancelled_order</td><td>Put</td><td>v1</td><td>The order has been cancelled.</td></tr><tr><td>NDR Submitted</td><td>ndr_resolution_submitted</td><td>Put</td><td>v1</td><td>Non-Delivery Report submitted for resolution.</td></tr><tr><td>Damage</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="148"></th><th width="102.66668701171875"></th><th width="79.33331298828125"></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>Return Created</td><td>created</td><td>Put</td><td>v1</td><td>A return request is created by the customer.</td></tr><tr><td>Pickup Pending</td><td>pickup_pending</td><td>Put</td><td>v1</td><td>Return pickup is scheduled but still pending.</td></tr><tr><td>Out for 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>Pickup Cancelled</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>Pickup Failed</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>Picked Up</td><td>picked_up</td><td>Put</td><td>v1</td><td>Return shipment has been successfully picked up.</td></tr><tr><td>In Transit</td><td>intransit</td><td>Put</td><td>v1</td><td>Return 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 return shipment to the warehouse.</td></tr><tr><td>Delivered</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>Delivered to WH</td><td>delivered_warehouse</td><td>Put</td><td>v2</td><td>Return shipment has been delivered to the warehouse.</td></tr><tr><td>Failed Delivery</td><td>failed_delivery</td><td>Put</td><td>v1</td><td>Return delivery attempt failed.</td></tr><tr><td>Return Complete</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>Return Approved</td><td>approved</td><td>Put</td><td>v1</td><td>Return shipment has been approved after quality checks.</td></tr><tr><td>Return 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>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://eshop.gitbook.io/eshopbox-developers/order/shipper-integration-wrapper-api/registering-webhook-for-tracking-shipment.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.