Webhook 回调通知使用说明
侯小猴
发布于 2024-08-10 13:13:37
推送机制
Webhook 是指当您的短链接被访问时,小码短链接将向您设定的 URL 上发送 POST 数据请求。
如果您需要接收此类消息来实现业务逻辑,需要:
- 开通公网可以访问的 IP 地址(或域名)和端口,如果需要对传输加密,请使用支持 HTTPS 的 URL 地址;
- 在 API 设置 中设置推送接收 URL ,以及用于签名验证的 token;
- 处理 POST 请求报文,实现业务逻辑。
您的服务器接收到某条 Webhook 消息后须在 5 秒内返回字符串 success,如果未返回 success,小码短链接将认为此条消息未能被成功处理,将触发推送重试机制,重试最多会进行 3 次,单次发送间隔分别为 5 秒、10 秒、20 秒。
推送消息示例
{
"scene": "xiaomark",
"url": "https://sourl.cn/HOHzsG",
"msgid": "5f72af532c7fbddd311a83cf",
"sign": "0a03e06acdf0dbff16e4e7888d056a3150839f6d",
"record": {
"id": "5f72af532c7fbddd311a83cf",
"visit_time": 1602750150,
"new_uv": true,
"ip": "180.97.118.219",
"country": "中国",
"region": "江苏",
"city": "南京",
"referer": "https://xiaomark.com/",
"browser": "chrome",
"os": "windows",
"device": "pc",
"net": "broad",
"z": "nanjing"
}
}
参数说明
名称 | 类型 | 描述 |
---|---|---|
scene | string | 场景值 |
url | string | 短链接 |
msgid | string | 消息id |
sign | string | 数字签名 |
record | object | 访问记录,详见下文访问记录信息 |
访问记录信息 record
名称 | 类型 | 描述 |
---|---|---|
id | string | 访问记录ID |
visit_time | integer | 访问时间(时间戳,以秒为单位) |
new_uv | bool | 是否为新访客 |
ip | string | IP |
country | string | 国家 |
region | string | 省份 |
city | string | 城市 |
referer | string | Referer(空字符串表示直接访问) |
browser | string | 浏览器: wechat - 微信,qq - QQ,tencent - QQ浏览器,sogou - 搜狗浏览器,uc - UC浏览器,ie - IE,edge - Edge, chrome - Chrome,safari - Safari,firefox - Firefox,other - 其它 |
os | string | 操作系统:ios/android/windows/mac/linux/other |
device | string | 设备类型:mobile - 移动设备,pc - 非移动设备 |
net | string | 网络类型:mobile - 移动网络,broad - 宽带网络 |
z | string | 自定义参数 |
验证签名
签名的目的在于验证 Webhook 是由小码短链接官方发起的,防止其他人恶意向 Webhook 接口发送伪造的访问数据。
签名验证方式:取 Webhook 签名验证 token(在 API 设置 中设置)、短链接 URL、msgid(消息 ID)这三个字段,将它们按字典序排序后拼接成一个字符串,然后进行 SHA1 数字签名,比较所得结果与 sign 字段值是否相等即可。