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 字段值是否相等即可。