This document provides detailed information about the webhook responses that your application will receive from our order driver to the customer. These webhook responses are designed to keep you informed about the status of orders as they move from your store or our warehouse to the customer. By integrating with these webhooks, you can receive real-time updates and take necessary actions based on the information provided.

Security Considerations

To ensure the security and integrity of webhook events sent to your system, a secret key is included in the headers of each request. This secret key, known only to you and your clients, acts as a unique identifier to validate the authenticity of the webhook events. When you register a webhook URL and callback key with our system, we include this callback key in the headers of every webhook event sent to your endpoint.
The following header is included in each webhook request:
the header name is secret-key and the value will be your registered callback key.

Webhook Response Structure

Each webhook response you receive will be in JSON format. JSON (JavaScript Object Notation) is a lightweight data-interchange format that is easy for both humans and machines to read and write. Here's an example of the general structure of a webhook response:

{
   //A unique identifier for the webhook event.
   "event_id":"evt_xxx",
   //The type of event that occurred. This field will indicate the nature of the event, such as "ForPacking," "packed," or other event types specific to your system.
   "event_type":"dynamic_value",
   //The timestamp indicating when the event was created, in UTC format.
   "created_on":"2023-08-12T15:53:17.5576294Z",
   //Your external reference associated with the event.
   "external_reference":"your_external_reference",
   //Additional data related to the event. The structure and content of this field.
   "event_data":{
       // Structure and content of event_data varies based on the event_type
   },
   //Links to related resources.
   "_links":{
      //A link to retrieve detailed information about the order in the Sandoog center.
      "get_order":{
         "href":"https:.../ord_***.pdf"
      },
      //A link to download the order invoice (PDF format).
      "get_order_receipt":{
         "href":"https:.../rct_ord_***.pdf"
      }
   }
}

Webhook Response Fields

event_id, event_type, created_on, external_reference, event_data, _links (get_order, get_order_receipt)

Order Statuses and Webhook Responses

Introduction

This section provides detailed information about the different order statuses that you will receive through webhook responses. Each order status represents a specific stage in the order fulfillment process. By integrating with these webhooks, you can keep track of the status of orders in real time and take necessary actions based on the information provided.

Placed

The "Placed" order status indicates that an order has been successfully placed by the customer. Here's an example of a webhook response for the "Placed" status:

{
  "event_id": "evt_xxx",
  "event_type": "Placed",
  "created_on": "2023-08-12T15:53:17.5576294Z",
  "external_reference": "your_external_reference",
  // Additional data for the "Placed" status
  "event_data": {
    "id": "ord_xx_sandoog_order_id",
    "fulfillment_id":"ful_yeqzp7qq6vbe7obqxny77ox5cq"
  },
  // Links relevant to the "Placed" status
   "_links":{
     //A link to retrieve detailed information about the order in the Sandoog center.
     "get_order":{
        "href":"https:.../ord_***.pdf"
     },
     //A link to download the order invoice (PDF format).
     "get_order_receipt":{
        "href":"https:.../rct_ord_***.pdf"
     }
  }
}

PickedUp

The "PickedUp" order status indicates that the order has been picked up for delivery. Here's an example of a webhook response for the "PickedUp" status:

{
  "event_id": "evt_xxx",
  "event_type": "PickedUp",
  "created_on": "2023-08-12T15:53:17.5576294Z",
  "external_reference": "your_external_reference",
  // Additional data for the "PickedUp" status
  "event_data": {
    "id": "ord_xx_sandoog_order_id",
    "fulfillment_id":"ful_yeqzp7qq6vbe7obqxny77ox5cq",
    "order_count": 1,//the value type is integer
    "note": "string",
    "address": "string",
    "pickup_date": "2023-08-12T15:53:17.5576294Z",
    "pickup_slot": {
      "name": "string",
      "from": "2023-08-12T15:53:17.5576294Z",
      "to": "2023-08-12T15:53:17.5576294Z"
    }
  },
  // Links relevant to the "PickedUp" status
  "_links":{
    //A link to retrieve detailed information about the order in the Sandoog center.
    "get_order":{
       "href":"https:.../ord_***.pdf"
    },
    //A link to download the order invoice (PDF format).
    "get_order_receipt":{
       "href":"https:.../rct_ord_***.pdf"
    }
 }
}

ForPacking

The "ForPacking" order status indicates that the order has been picked up for delivery. Here's an example of a webhook response for the "ForPacking" status:

{
  "event_id": "evt_xxx",
  "event_type": "ForPacking",
  "created_on": "2023-08-12T15:53:17.5576294Z",
  "external_reference": "your_external_reference",
  // Additional data for the "ForPacking" status
  "event_data": {
    "id": "ord_xx_sandoog_order_id",
    "fulfillment_id":"ful_yeqzp7qq6vbe7obqxny77ox5cq"
  },
  // Links relevant to the "ForPacking" status
  "_links":{
    //A link to retrieve detailed information about the order in the Sandoog center.
    "get_order":{
       "href":"https:.../ord_***.pdf"
    },
    //A link to download the order invoice (PDF format).
    "get_order_receipt":{
       "href":"https:.../rct_ord_***.pdf"
    }
  }
}

Packed

The "Packed" status indicates that the items in the order have been successfully packed and are ready for shipment. This status confirms that the products have been carefully prepared for delivery to the customer's location.
response for the "Packed" status:

{
  "event_id": "evt_xxx",
  "event_type": "Packed",
  "created_on": "2023-08-12T15:53:17.5576294Z",
  "external_reference": "your_external_reference",
  // Additional data for the "Packed" status
  "event_data": {
    "id": "ord_xx_sandoog_order_id",
    "fulfillment_id":"ful_yeqzp7qq6vbe7obqxny77ox5cq"
  },
  // Links relevant to the "Packed" status
  "_links":{
    //A link to retrieve detailed information about the order in the Sandoog center.
    "get_order":{
       "href":"https:.../ord_***.pdf"
    },
    //A link to download the order invoice (PDF format).
    "get_order_receipt":{
       "href":"https:.../rct_ord_***.pdf"
    }
  }
}

OnDelivery

The "OnDelivery" status signifies that the order is currently in transit and en route to the customer's address. The products are being actively delivered, and this status provides real-time tracking as the order makes its way to its destination.
response for the "OnDelivery" status:

{
  "event_id": "evt_xxx",
  "event_type": "OnDelivery",
  "created_on": "2023-08-12T15:53:17.5576294Z",
  "external_reference": "your_external_reference",
  // Additional data for the "OnDelivery" status
  "event_data": {
    "id": "ord_xx_sandoog_order_id",
    "fulfillment_id":"ful_yeqzp7qq6vbe7obqxny77ox5cq",
    "driver_data": {
      "driver_name": "string",
      "driver_phone": "string",
      "latitude": "string",
      "longitude": "string",
    }
  },
  // Links relevant to the "OnDelivery" status
  "_links":{
    //A link to retrieve detailed information about the order in the Sandoog center.
    "get_order":{
       "href":"https:.../ord_***.pdf"
    },
    //A link to download the order invoice (PDF format).
    "get_order_receipt":{
       "href":"https:.../rct_ord_***.pdf"
    }
  }
}

Delivered

The "Delivered" status confirms the successful completion of the order. It indicates that the products have been successfully delivered to the customer's specified location and received in good condition.
response for the "Delivered" status:

{
  "event_id": "evt_xxx",
  "event_type": "Delivered",
  "created_on": "2023-08-12T15:53:17.5576294Z",
  "external_reference": "your_external_reference",
  // Additional data for the "Delivered" status
  "event_data": {
    "id": "ord_xx_sandoog_order_id",
    "fulfillment_id":"ful_yeqzp7qq6vbe7obqxny77ox5cq"
  },
  // Links relevant to the "Delivered" status
  "_links":{
    //A link to retrieve detailed information about the order in the Sandoog center.
    "get_order":{
       "href":"https:.../ord_***.pdf"
    },
    //A link to download the order invoice (PDF format).
    "get_order_receipt":{
       "href":"https:.../rct_ord_***.pdf"
    }
  }
}

Complete

The "Complete" status signifies the complete execution of the order, encompassing all stages from processing to delivery. Orders in this status have been successfully packed, delivered, and received by the customer.
response for the "Complete" status:

{
  "event_id": "evt_xxx",
  "event_type": "Complete",
  "created_on": "2023-08-12T15:53:17.5576294Z",
  "external_reference": "your_external_reference",
  // Additional data for the "Complete" status
  "event_data": {
    "id": "ord_xx_sandoog_order_id",
    "fulfillment_id":"ful_yeqzp7qq6vbe7obqxny77ox5cq"
  },
  // Links relevant to the "Complete" status
  "_links":{
    //A link to retrieve detailed information about the order in the Sandoog center.
    "get_order":{
       "href":"https:.../ord_***.pdf"
    },
    //A link to download the order invoice (PDF format).
    "get_order_receipt":{
       "href":"https:.../rct_ord_***.pdf"
    }
  }
}

ToReturn

The "ToReturn" status indicates that the customer has initiated a return request for specific items within the order. This status marks the beginning of the return process and prompts further action to process the return smoothly.
response for the "ToReturn" status:

{
  "event_id": "evt_xxx",
  "event_type": "ToReturn",
  "created_on": "2023-08-12T15:53:17.5576294Z",
  "external_reference": "your_external_reference",
  // Additional data for the "ToReturn" status
  "event_data": {
    "id": "ord_xx_sandoog_order_id",
    "fulfillment_id":"ful_yeqzp7qq6vbe7obqxny77ox5cq"
  },
  // Links relevant to the "ToReturn" status
  "_links":{
    //A link to retrieve detailed information about the order in the Sandoog center.
    "get_order":{
       "href":"https:.../ord_***.pdf"
    },
    //A link to download the order invoice (PDF format).
    "get_order_receipt":{
       "href":"https:.../rct_ord_***.pdf"
    }
  }
}

Returned

The "Returned" status confirms the completion of the return process. It indicates that the returned items have been received, inspected, and processed successfully, and any necessary refunds or replacements have been initiated.
response for the "Returned" status:

{
  "event_id": "evt_xxx",
  "event_type": "Returned ",
  "created_on": "2023-08-12T15:53:17.5576294Z",
  "external_reference": "your_external_reference",
  // Additional data for the "Returned" status
  "event_data": {
    "id": "ord_xx_sandoog_order_id",
    "fulfillment_id":"ful_yeqzp7qq6vbe7obqxny77ox5cq"
  },
  // Links relevant to the "Returned" status
  "_links":{
    //A link to retrieve detailed information about the order in the Sandoog center.
    "get_order":{
       "href":"https:.../ord_***.pdf"
    },
    //A link to download the order invoice (PDF format).
    "get_order_receipt":{
       "href":"https:.../rct_ord_***.pdf"
    }
  }
}

Failed

The "Failed" status denotes an unsuccessful attempt to fulfill or deliver the order. This status can arise due to various reasons, such as failed payment, logistical issues, or other challenges that prevent the successful completion of the order.
response for the "Failed" status:

{
  "event_id": "evt_xxx",
  "event_type": "Failed",
  "created_on": "2023-08-12T15:53:17.5576294Z",
  "external_reference": "your_external_reference",
  // Additional data for the "Failed" status
  "event_data": {
    "id": "ord_xx_sandoog_order_id",
    "fulfillment_id":"ful_yeqzp7qq6vbe7obqxny77ox5cq",
    "reason": "string",
    "reason_code": "string"
  },
  // Links relevant to the "Failed" status
  "_links":{
    //A link to retrieve detailed information about the order in the Sandoog center.
    "get_order":{
       "href":"https:.../ord_***.pdf"
    },
    //A link to download the order invoice (PDF format).
    "get_order_receipt":{
       "href":"https:.../rct_ord_***.pdf"
    }
  }
}

Cancelled

The "Cancelled" status indicates that a previously placed order has been successfully canceled by either the customer or the system. This status confirms that the requested cancellation action has been processed and applied to the order. Any associated transactions, inventory adjustments, or other relevant actions have been reversed or updated accordingly.
response for the "Cancelled" status:

{
  "event_id": "evt_xxx",
  "event_type": "Cancelled",
  "created_on": "2023-08-12T15:53:17.5576294Z",
  "external_reference": "your_external_reference",
  // Additional data for the "Cancelled" status
  "event_data": {
    "id": "ord_xx_sandoog_order_id",
    "fulfillment_id":"ful_yeqzp7qq6vbe7obqxny77ox5cq"
  },
  // Links relevant to the "Cancelled" status
  "_links":{
    //A link to retrieve detailed information about the order in the Sandoog center.
    "get_order":{
       "href":"https:.../ord_***.pdf"
    },
    //A link to download the order invoice (PDF format).
    "get_order_receipt":{
       "href":"https:.../rct_ord_***.pdf"
    }
  }
}

Integration Guidelines

To integrate with our webhook system and start receiving these order-related events, please register your webhook URL using Sandoog API.

Conclusion

Integrating with our webhook system provides you with real-time updates and information about various events in your order fulfillment process. As events can have different types and data structures, we recommend referring to specific event documentation for accurate interpretation.

For detailed information about event_data and event_type specific to each event, please consult the dedicated documentation for each event type. If you have any questions or require assistance, please don't hesitate to contact our support team at [email protected].

We trust that this documentation will assist you in comprehending and effectively utilizing the dynamic webhook responses from our order driver to customer service. Should you require specific customization or additional details, feel free to adapt the document to your needs.