5. Webhook
Overview
A webhook (also called a web callback) is a way for an application to provide real-time information. GHTK uses webhooks to send notifications to partners upon order status changes. Every partner needs to provide GHTK with a callback URL endpoint to receive instant updates upon order status changes.
Example Callback URL
Request Example
An order with label ID: “S1.A1.17373471” (partner ID: “1234567”) has been updated to “successfully delivered”.
GHTK will send a request to the partner’s callback link as shown below:
{
"partner_id": "1234567",
"label_id": "S1.A1.17373471",
"status_id": 5,
"action_time": "2016-11-02T12:18:39+07:00",
"reason_code": "",
"reason": "",
"weight": 2.4,
"fee": 15000,
"pick_money": 100000,
"return_part_package": 0
}
Suppose the partner’s callback link is https://partner_example.com/updateShipment?hash=XXX, GHTK’s server will send:
POST /updateShipment?hash=XXX HTTP/1.1
Host: partner_example.com
Content-Type: application/x-www-form-urlencoded
label_id=S1.A1.17373471&partner_id=1234567&action_time=2016-11-02T12:18:39+07:00&status_id=5&reason_code=&reason=&weight=2.4&fee=1500&return_part_package=0
GHTK considers HTTP 200 OK as the only successful response.
If the response is null or different from 200, GHTK will resend the request.
Input Parameters
| Parameter | Datatype | Description |
|---|---|---|
| label_id | String | GHTK’s reference ID (order.label) |
| partner_id | String | Partner’s reference ID |
| status_id | Integer | Status code (refer to table below for list of status code) |
| action_time | String | Represents time of updating order status. Format: ISO 8601 |
| reason_code | Integer | Reason code for update |
| reason | String | Reason in text |
| weight | Float | Package weight in kilograms |
| fee | Integer | Shipping fee (in VND) |
| return_part_package | Integer | Indicates if the order is a partial shipment. “1” if it is a partial shipment |
| cur_station.address_l0 - cur_station.address_l3 | String | 4 levels of addresses |
| cur_station.site_name | String | Name of the current station |
| images | Array | Images for picking (status 3, 123), delivering (status 45, 5, 9) and returning (status 21) |
| pod.proof_url | Array | Proof of delivery image urls at status 5, 45 |
Station Information
For statuses that include station information, the following parameters will be attached:
{
"cur_station": {
"address_l0": "VN",
"address_l1": "Hà Nội",
"address_l2": "Quận Long Biên",
"address_l3": "Phường Long Biên",
"site_name": "LV - Đài Tư"
}
}
Package Images
For statuses that include images and partner is configured to show the images, the following parameters will be attached:
{
"images": [
"https://cache.giaohangtietkiem.vn/d/img1.jpg",
"https://cache.giaohangtietkiem.vn/d/img2.jpg"
]
}
POD
For statuses that include proof of delivery (POD) images and partner is configured to use POD, the following parameters will be attached:
{
"pod": {
"proof_url": [
"https://cache.giaohangtietkiem.vn/d/pod1.jpg",
"https://cache.giaohangtietkiem.vn/d/pod2.jpg",
"https://cache.giaohangtietkiem.vn/d/pod3.jpg",
"https://cache.giaohangtietkiem.vn/d/pod4.jpg"
]
}
}
Order Statuses
Order Status Details
| Status | Description |
|---|---|
| -1 | Canceled order |
| 1 | Not Confirmed: Order submitted to GHTK’s system is awaiting validation and confirmation by the distributor. |
| 2 | Confirmed: The order is successfully submitted and a carrier will be assigned to pick up the order. |
| 3 | Picked/In warehouse: Carrier picked the order and put it in the warehouse. |
| 4 | Delivering: Carrier is on the way to deliver the order. |
| 5 | Delivered: Order is delivered successfully. |
| 6 | Reconciled (in case of successful delivery). Prior status is “5: Delivered”. |
| 7 | Failed to Pick Up (over 3 attempts or shop requested to cancel the order before it is picked up). |
| 8 | Delay Picking Up. |
| 9 | Failed to Deliver (over 3 attempts). The return process will be triggered. |
| 10 | Delay Delivering. |
| 11 | Reconciled (in case of failed delivery). Prior stage is “9: Failed to Deliver”. |
| 12 | Picking Up: Carrier is on the way to pick up the order. |
| 13 | Compensation order. |
| 20 | Returning: Carrier attempts a maximum of 3 times to return. |
| 21 | Returned: Package order is returned to the shop. |
| 30 | Package arrived at the intermediary station. |
| 31 | Package departed from the intermediary station. |
| 91 | Arrival at the destination depot |
| 123 | Carrier reports order is picked up. |
| 127 | Carrier reports order is failed to pick up. |
| 128 | Carrier reports delay picking up. |
| 45 | Carrier reports order is delivered. |
| 49 | Carrier reports order is failed to deliver. |
| 410 | Carrier reports delay delivering. |
| 26 | Enter returned goods into warehouse |
Warning
Note: Status codes 123, 127, 128, 45, 49, and 410 are internal processing stages for notification only and are not returned as order statuses in this API.
Reason Codes
Delay Picking Up (status_id=8)
| reason_code | Description |
|---|---|
| 100 | Shop requests to delay picking up until the next shift |
| 101 | Unable to contact shop owners |
| 102 | Package order is not ready for picking up |
| 103 | Shop changes pick-up address |
| 104 | Shop changes the date of picking-up |
| 105 | Carrier is overloaded |
| 106 | Objective factors (e.g., weather) |
| 107 | Others |
Failed to Pick Up (status_id=7)
| reason_code | Description |
|---|---|
| 110 | Pick-up address is not supported |
| 111 | Product is not allowed to be delivered (e.g., prohibited products) |
| 112 | Shop requests to cancel order |
| 113 | Over 3 pick-up attempts |
| 114 | Others |
| 115 | Partner requests to cancel order via API |
Delay Delivering (status_id=10)
| reason_code | Description |
|---|---|
| 120 | Carrier is overloaded |
| 121 | Customer requests to delay until the next shift |
| 122 | Unable to contact customer |
| 123 | Customer requests to receive at another time |
| 124 | Customer changes delivery address |
| 125 | Wrong address; shop needs to double-check |
| 126 | Objective factors (e.g., weather conditions) |
| 127 | Others |
| 128 | Shop changes delivery time |
| 129 | Package is not found |
| 1200 | Wrong contact number; shop needs to double-check |
Failed to Deliver (status_id=9)
| reason_code | Description |
|---|---|
| 130 | Customer refuses to receive the products |
| 131 | Unable to contact over 3 times |
| 132 | Customer requests to delay over 3 times |
| 133 | Shop requests to cancel order |
| 134 | Others |
| 135 | Partner requests to cancel order via API |
Delay Returning
| reason_code | Description |
|---|---|
| 140 | Shop requests to delay until the next shift |
| 141 | Unable to contact shop owners |
| 142 | Shop is not at the returning address |
| 143 | Shop requests to receive the returning order at another time |
| 144 | Others |