Webhooks
Introduction
You can subscribe to tracking updates for a package (such as updating the package status). Our system will send the latest status to your application or software or SaaS tools through the webhook.
Shipment Status Update
You should create a shipment status auto-update request through the "Create Tracking" API. KeyDelivery will send a request to the webhook URL whenever the shipment status changes. KeyDelivery will send a POST request to the webhook_url that you provided in the "Create Tracking" API whenever you execute the webhook.
The format of the message you receive is as follows.
Headers
| Key | Value |
| Content-Type | application/json |
Header
Content-Type: application/json
Body
| Name | Data Type | Required | Note |
|---|---|---|---|
| event | string | true | shipment status |
| message | string | true | event text |
| carrier_id | string | true | carrier ID |
| tracking_number | string | true | tracking number |
| signer | number | true | whether is shipment is received or rejected |
| order_status_code | number | false | the latest shipment status |
| --items | object [] | false | |
| context | string | true | shipment route description |
| time | string | true | shipment route timestamp |
| order_status_code | string | true | shipment status code. You need to set the parameter (area_show) value to "1" to use this feature. |
| order_status_description | string | true | shipment status description. You need to set the parameter (area_show) value to "1" to use this feature. |
| area_name | string | true | shipment route area information. You need to set the parameter (area_show) value to "1" to use this feature. |
| location | string | true | shipment route location information. You need to set the parameter (area_show) value to "1" to use this feature. |
When the message is received, It is necessary to respond in the following format.
Reminder: For shipping orders with "expired" status (the message shows that "No tracking information for 3 days" or "No status update for 60 days"), it is necessary to return the successfully received response message and code to KeyDelivery.If the code status is 200, it will determine that you have received the status update successfully. Otherwise, KeyDelivery will resend the result to your webhook 30 minutes later. KeyDelivery attempts to deliver it to your webhooks 3 times at most, or it will stop sending the status update.
Parameters
{
"event": "completed",
"message": "OK",
"carrier_id": "dhl",
"tracking_number": "6981236054",
"signer": 1,
"order_status_code": 4,
"items": [
{
"context": "Partial delivery",
"time": "2021-07-09 18:47:17",
"order_status_description": "Delivered",
"area_name": "null",
"location": "null"
},
{
"context": "With delivery courier",
"time": "2021-07-09 18:47:02",
"order_status_description": "Out for delivery",
"area_name": "null",
"location": "null"
},
{
"context": "Arrived at Delivery Facility",
"time": "2021-07-08 19:13:10",
"order_status_description": "In transit",
"area_name": "null",
"location": "null"
},
{
"context": "Shipment picked up",
"time": "2021-05-25 04:57:39",
"order_status_description": "Accepted",
"area_name": null,
"location": null
}
]
}
Responses
| Name | Data Type | Required | Note |
|---|---|---|---|
| code | number | true | If you successfully received the tracking status update, return and only return 200 for the code. You can define other codes by yourself if you think it is necessary. |
| message | string | false | Please customize the event text according to your code. |
Response
{
"code": 200,
"message": "OK"
}