Getting Started with Webhooks

Sections in this article

• What are Webhooks?
• How to Setup a Webhook?
• Webhook Events and Their Payload
• Webhook Signature

What are Webhooks?

Webhooks are one of a few ways web applications can communicate with each other. It allows you to send real-time data on a set webhook URL to an application whenever a set event occurs.

---

How to Setup a Webhook?

Please follow the below steps to setup a webhook:

1. Go to Webhooks in Settings.

2. Click on Add Endpoint button.

   

3. Add the URL, description and select the required events and click on Add Endpoint.

   

4. The endpoint should be triggered when one the selected events are triggered.

---

Webhook Events and Their Payload

Please refer to the below mentioned event specific headers:

Order.Created POST

{
   "event": String;                      // ("order.created")
   "items": [
      {
         "shipment": {
            "estimatedamount": Number;
            "mode": Number;
            "zone": String;            
            "isInsured": Boolean;
         },
         "order": {
            "id": Number;
            "orderID": String;
            "channel": String;   
            "customer": {
               "name": String;
               "city": String;
               "pincode": String;
            },
         }
      }
   ]
}

Payload Attributes

1. event: Event Type
2. items: Array of created orders
   1. shipment: Shipment Information
      1. estimatedamount: Estimated billing amount for shipment
      2. mode: Shipment mode (Appendix)
      3. zone: Shipping zone (Appendix)
      4. isInsured: Shipment insurance flag
   2. order: Order information
      1. id: Shyplite Order ID
      2. orderID: Unique Order ID
      3. channel: Order creation channel (Appendix)
      4. customer: Shipment destination details

---

Order.Booked POST

   {
      "event": String;                    // ("order.booked")
      "items": [
         {
            "shipment": {
               "estimatedamount": Number;
               "mode": Number;
               "zone": String;          
               "isInsured": Boolean;
            },
            "order": {
               "importedID": Number;
               "channel": String;        
               "customer": {
                  "name": String;
                  "city": String;
                  "pincode": String;
               }
            },
            "tracking": {
               "awbNo": String;
               "status": Number;
               "carrier": String;
               "deliveryDate": String;
               "isCancelled": Boolean;
               "returnOrReverse": Boolean;
            },
            "slipURL": String;
         }
      ]
   }

Payload Attributes

1. event: Event Type
2. items: Array of booked orders
   1. shipment: Shipment Information
      1. estimatedamount: Estimated billing amount for shipment
      2. mode: Shipment mode (Appendix)
      3. zone: Shipping zone (Appendix)
      4. isInsured: Shipment insurance flag
   2. order: Order information
      1. id: Shyplite Order ID
      2. orderID: Unique Order ID
      3. channel: Order creation channel (Appendix)
      4. customer: Shipment destination details
   3. tracking: Tracking information
      1. awbNo: Airway Bill Number
      2. status: Tracking status
      3. carrier: Shipment Carrier
      4. deliveryDate: Delivery timestamp - ISO Encoded Date String
      5. isCancelled: Cancellation Status
      6. returnOrReverse: Shipment returning or reversed
   4. slipURL: Manifest Slip PDF Download location

---

Order.Cancelled POST

   {
      "event": String;                    // ("order.cancelled")
      "items": [
         {
            "orderID": String;
         }
      ]
   }

Payload Attributes

1. event: Event Type
2. items: Array of cancelled orders
   1. orderID: Unique Order ID

---

Tracking.PickedUp POST

   {
      "event": String;                              // ("tracking.pickedup")
      "items": [
         {
            "shipment": {
               "estimatedamount": Number;
               "mode": Number;
               "zone": String;
               "isInsured": Boolean;
            },
            "order": {
               "orderID": Number;
               "channel": String;
               "customer": {
                  "name": String;
                  "city": String;
                  "pincode": String;
               }
            },
            "tracking": {
               "awbNo": String;
               "status": Number;
               "carrier": String;
               "deliveryDate": String;
               "isCancelled": Boolean;
               "returnOrReverse": Boolean;
            },
            "event": {
               "currentLocation": String;
               "statusTime": String;
               "remarks": String;
               "status": Number;
            }
         }
      ]
   }

Payload Attributes

1. event: Event Type
2. items: Array of picked up shipments
   1. shipment: Shipment Information
      1. estimatedamount: Estimated billing amount for shipment
      2. mode: Shipment mode (Appendix)
      3. zone: Shipping zone (Appendix)
      4. isInsured: Shipment insurance status
   2. order: Shipment Information
      1. id: Shyplite Order ID
      2. orderID: Unique Order ID
      3. channel: Order placement channel (Appendix)
      4. customer: Shipment destination details
   3. tracking: Tracking information
      1. awbNo: Airway Bill Number
      2. status: Tracking status
      3. carrier: Shipment Carrier
      4. deliveryDate: Delivery timestamp - ISO Encoded Date String
      5. isCancelled: Cancellation Status
      6. returnOrReverse: Shipment returning or reversed
   4. event: Tracking Event information
      1. currentLocation: Shipment location
      2. statusTime: Event timestamp
      3. remarks: Event remarks
      4. status: Event status from carrier

---

Tracking.OutForDelivery POST

   {
      "event": String;                              // ("tracking.outfordelivery")
      "items": [
         {
            "shipment": {
               "estimatedamount": Number;
               "mode": Number;
               "zone": String;
               "isInsured": Boolean;
            },
            "order": {
               "id": Number
               "orderID": String;
               "channel": String;
               "customer": {
                  "name": String;
                  "city": String;
                  "pincode": String;
               }
            },
            "tracking": {
               "awbNo": String;
               "status": Number;
               "carrier": String;
               "isCancelled": Boolean;
               "returnOrReverse": Boolean;
            },
            "event": {
               "currentLocation": String;
               "statusTime": String;
               "remarks": String;
               "status": Number;
            }
         }
      ]
   }

Payload Attributes

1. event: Event Type
2. items: Array of picked up shipments
   1. shipment: Shipment Information
      1. estimatedamount: Estimated billing amount for shipment
      2. mode: Shipment mode (Appendix)
      3. zone: Shipping zone (Appendix)
      4. isInsured: Shipment insurance status
   2. order: Shipment Information
      1. id: Shyplite Order ID
      2. orderID: Unique Order ID
      3. channel: Order placement channel (Appendix)
      4. customer: Shipment destination details
   3. tracking: Tracking information
      1. awbNo: Airway Bill Number
      2. status: Tracking status
      3. carrier: Shipment Carrier
      4. isCancelled: Cancellation Status
      5. returnOrReverse: Shipment returning or reversed
   4. event: Tracking Event information
      1. currentLocation: Shipment location
      2. statusTime: Event timestamp
      3. remarks: Event remarks
      4. status: Event status from carrier

---

Tracking.ReturnOrReverse POST

   {
      "event": String;                              // ("tracking.returnOrReverse")
      "items": [
         {
            "shipment": {
               "estimatedamount": Number;
               "mode": Number;
               "zone": String;
               "isInsured": Boolean;
            },
            "order": {
               "id": Number
               "orderID": String;
               "channel": String;
               "customer": {
                  "name": String;
                  "city": String;
                  "pincode": String;
               }
            },
            "tracking": {
               "awbNo": String;
               "status": Number;
               "carrier": String;
               "isCancelled": Boolean;
               "returnOrReverse": Boolean;         // true
            },
            "event": {
               "currentLocation": String;
               "statusTime": String;
               "remarks": String;
               "status": Number;
            }
         }
      ]
   }

Payload Attributes

1. event: Event Type
2. items: Array of picked up shipments
   1. shipment: Shipment Information
      1. estimatedamount: Estimated billing amount for shipment
      2. mode: Shipment mode (Appendix)
      3. zone: Shipping zone (Appendix)
      4. isInsured: Shipment insurance status
   2. order: Shipment Information
      1. id: Shyplite Order ID
      2. orderID: Unique Order ID
      3. channel: Order placement channel (Appendix)
      4. customer: Shipment destination details
   3. tracking: Tracking information
      1. awbNo: Airway Bill Number
      2. status: Tracking status
      3. carrier: Shipment Carrier
      4. isCancelled: Cancellation Status
      5. returnOrReverse: Shipment returning or reversed
   4. event: Tracking Event information
      1. currentLocation: Shipment location
      2. statusTime: Event timestamp
      3. remarks: Event remarks
      4. status: Event status from carrier

---

Tracking.Delivered POST

   {
      "event": String;                        // ("tracking.delivered")
      "items": [
         {
            "shipment": {
               "estimatedamount": Number;
               "mode": Number;
               "zone": String;                   
               "isInsured": false
            },
            "order": {
               "orderID": Number;
               "channel": String;
               "customer": {
                  "name": String;
                  "city": String;
                  "pincode": String;
               }
            },
            "tracking": {
               "awbNo": String;
               "status": Number;              
               "carrier": String;
               "deliveryDate": Date;
               "isCancelled": false,
               "returnOrReverse": false
            },
            "event": {
               "currentLocation": String;
               "statusTime": Date;
               "remarks": String;
               "status": Number;
            }
         }
      ]
   }

Payload Attributes

1. event: Event Type
2. items: Array of created orders
   1. shipment: Shipment Information
      1. estimatedamount: Estimated billing amount for shipment
      2. mode: Shipment mode (Appendix)
      3. zone: Shipping zone (Appendix)
      4. isInsured: Shipment insurance status
   2. order: Order Information
      1. id: Shyplite Order ID
      2. orderID: Unique Order ID
      3. channel: Order creation channel (Appendix)
      4. customer: Order destination details
   3. tracking: Tracking information
      1. awbNo: Airway Bill Number
      2. status: Tracking status
      3. carrier: Shipment Carrier
      4. deliveryDate: Delivery timestamp - ISO Encoded Date String
      5. isCancelled: Cancellation Status
      6. returnOrReverse: Shipment returning or reversed
   4. event: Tracking Event information
      1. currentLocation: Shipment location
      2. statusTime: Event timestamp
      3. remarks: Event remarks
      4. status: Event status from carrier

---

Webhook Signature

All webhook requests sent from our hubs will include an additional header which is the signature of the payload being sent in the request.

It is recommended that you validate this signature to ensure the authenticity and validity of the payload. This ensures that if any third party sends a request to your webhook URL, you are able to catch this in a timely manner to prevent any adverse effects on your systems and data.

To verify the signature:

1. The signing key (which is available on the endpoint’s page). It is hidden by default, click on the button to reveal it.

2. The signature from the request you have received on your endpoint. A typical headers set will look as follows:

   connection: close
   host: webhook.site
   accept-encoding: gzip, deflate, br
   content-length: 40
   content-type: application/json
   x-req-id: eb4282a2-17ca-4bfd-843f-3e51f059ea3f
   x-hub-signature: Tukw1P2eYVb3qAQhK7zsHA8IYEVaoqIcbIZ7Yhj27+o=
   user-agent: Shyplite Hub 1
   

   We need the x-hub-signature key from the above set. This is the signature computed by Shyplite against the payload.

3. The payload itself. In a typical ExpressJS app, this would be: req.body.

const signingKey = "...." 

// if using a Body Parser middleware
const payloadString = JSON.stringify(Object.assign({}, req.body))

// if not using any Body Parser middleware
const payloadString = JSON.stringify(req.body.toString("utf8"))

const signature = crypto.createHmac('sha256', signingKey).update(payloadString).digest("base64")

const headerValue = req.headers["x-hub-signature"]

assert.equal(signature, headerValue)

If the signature you generate does not match the header value, it is recommended that you immediately close the connection and drop the request.

If you have any questions that are not addressed, please feel free to reach Shyplite Support.

Jun 9, 2020 by Shyplite

Related Articles

• Getting Started With Shyplite API
• How to Integrate Amazon Store with Shyplite?
• How to Integrate Flipkart Store with Shyplite?
• How to Integrate Your Shopify Store with Shyplite?
• How to Integrate Your Woocommerce Store with Shyplite?