介绍
# 什么是 Webhook?
Webhook是用户通过自定义回调函数的方式来改变Web应用的一种行为。通过Webhook,您可以自定义一些行为通知到指定的URL去。当请求数据完成,Webhook会通过您设置的URL将对应数据响应给您。 当查询到物流信息有更新,且触发了你在设置中的状态更新提醒时,系统会做出一个POST请求发送到你在webhook页面自定义的回调url上。
# POST主体包含了以下数据的JSON字符串:
{
"data": {
"createTime": "2021-09-24 14:57:51",
"deliveredDays": 4,
"deliveredTime": "2021-08-12 10:32:41",
"id": 229255084490768384,
"lastTrackingTime": "2021-08-12 10:32:41",
"localLogisticsInfo": {
"courierCode": "4px",
"courierHomePage": "http://express.4px.com/",
"courierNameCN": "递四方",
"courierNameEN": "4PX",
"trackingDetails": [
{
"address": "Mableton, GA",
"eventDetail": "Delivered",
"eventTime": "2021-08-12 10:32:41",
"transitSubStatus": "DELIVERED_01"
},
{
"address": "AUSTELL, GA",
"eventDetail": "On fedex vehicle for delivery",
"eventTime": "2021-08-12 03:09:00",
"transitSubStatus": "WAITING_DELIVERY_01"
},
{
"address": "AUSTELL, GA",
"eventDetail": "Arrived at fedex location",
"eventTime": "2021-08-12 03:04:00",
"transitSubStatus": "IN_TRANSIT_01"
},
{
"address": "AUSTELL, GA",
"eventDetail": "In transit",
"eventTime": "2021-08-11 17:26:46",
"transitSubStatus": "IN_TRANSIT_01"
},
{
"address": "KENNESAW, GA",
"eventDetail": "Departed fedex location",
"eventTime": "2021-08-11 04:30:39",
"transitSubStatus": "IN_TRANSIT_01"
},
{
"address": "EDISON, NJ",
"eventDetail": "Departed fedex location",
"eventTime": "2021-08-09 10:27:51",
"transitSubStatus": "IN_TRANSIT_01"
},
{
"address": "USNYCA",
"eventDetail": "Packing the operating point",
"eventTime": "2021-08-07 00:40:24",
"transitSubStatus": "INFO_RECEIVED_01"
},
{
"address": "USNYCA",
"eventDetail": "Picking the operating point",
"eventTime": "2021-08-07 00:13:57",
"transitSubStatus": "INFO_RECEIVED_01"
},
{
"address": "",
"eventDetail": "Shipment information sent to fedex",
"eventTime": "2021-08-06 17:34:00",
"transitSubStatus": "INFO_RECEIVED_01"
}
]
},
"orderTime": "2021-08-06 17:34:00",
"receiptDays": 39,
"receiptTime": "2021-08-09 10:27:51",
"shipFrom": "US",
"shipTime": "2021-07-01 12:30:31",
"shipTo": "US",
"trackNo": "282295361468",
"transitStatus": "DELIVERED",
"transitSubStatus": "DELIVERED_01"
},
"verify": {
"signature": "e53cf138931ad85d20955dfc6a0355e777f915a4f511e147c9bd2c6942273151",
"timestamp": "1632466678868"
}
}
# 签名验证
为了确保消息的来源身份是 Track123,你可以选择对 POST 数据的来源进行安全认证。 ( 不验证,直接解析 POST 的数据也可以 ) 安全认证的方法如下:
- 解析出 POST 数据中的 timestamp 和 signature 这两个参数。
- 使用你的 Track123 API key 和 timestamp (明文) 生成签名 signature, 与 POST 数据中的 signature 进行校验 ( 签名算法: PHP:SHA256、JAVA:HmacSHA256)
# 怎么使用?
- 登录Track123会员系统,设置你 webhook url 和需要提醒的状态: https://member.track123.com/notification (opens new window)
- 当服务器检测到单号更新且满足你的设置的时候,会将更新后的数据推送到设置的 webhook url 路径上。所以你需要预先在这个 webhook url 写好你自己的程序,对接收到的 webhook 数据进行处理。
- Webhook重试:当你的url无法连接,或设置了须返回200响应,但服务器推送时没有得到正确的HTTP响应码时,服务端会重新尝试推送。重试的规则为:重试6次,按照下列方式进行重试。
尝试次数 | 重试次数 | 重试间隔(秒) | 描述 |
---|---|---|---|
1 | 0 | 0 | 无。 |
2 | 1 | 600 | 第 10 分钟发起。 |
3 | 2 | 1800 | 第 30 分钟发起。 |
4 | 3 | 3600 | 第 1 个小时发起。 |
5 | 4 | 14400 | 第 4 个小时发起。 |
6 | 5 | 43200 | 第 12 个小时发起。 |
7 | 6 | 129600 | 第 36 个小时发起。 |