Webhook 回调通知使用说明

侯小猴

发布于 2024-08-10 13:13:37

推送机制

Webhook 是指当您的短链接被访问时，小码短链接将向您设定的 URL 上发送 POST 数据请求。

如果您需要接收此类消息来实现业务逻辑，需要:

开通公网可以访问的 IP 地址（或域名）和端口，如果需要对传输加密，请使用支持 HTTPS 的 URL 地址；
在 API 设置中设置推送接收 URL ，以及用于签名验证的 token；
处理 POST 请求报文，实现业务逻辑。

您的服务器接收到某条 Webhook 消息后须在 5 秒内返回字符串 success，如果未返回 success，小码短链接将认为此条消息未能被成功处理，将触发推送重试机制，重试最多会进行 4 次，单次发送间隔分别为 5 秒、10 秒、30 秒、60 秒。

推送消息示例

{
    "scene": "xiaomark",
    "url": "https://sourl.cn/HOHzsG",
    "msgid": "5f72af532c7fbddd311a83cf",
    "sign": "0a03e06acdf0dbff16e4e7888d056a3150839f6d",
    "record": {
        "id": "5f72af532c7fbddd311a83cf",
        "visit_time": 1602750150,
        "ip": "180.97.118.219",
        "referer": "https://xiaomark.com/",
        "target_url": "https://portal.xiaomark.com/",
        "z": "nanjing",
        "new_visitor": true,
        "is_robot": false,
        "country_code": "CN",
        "country": "中国",
        "region": "江苏",
        "city": "南京",
        "browser": "chrome",
        "os": "windows",
        "device": "pc",
        "network": "broadband"
    }
}

参数说明

名称	类型	描述
scene	string	场景值
url	string	短链接
msgid	string	消息id
sign	string	数字签名
record	object	访问记录，详见下文访问记录信息

访问记录信息 record

名称	类型	描述
id	string	访问记录ID
visit_time	integer	访问时间（时间戳，以秒为单位）
ip	string	IP
referer	string	访问来源（空字符串表示直接访问）
target_url	string	跳转目标链接
z	string	自定义参数
new_visitor	boolean	是否为新访客
is_robot	boolean	是否为机器访问
country_code	string	国家代码
country	string	国家
region	string	省份
city	string	城市
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/macos/linux/other
device	string	设备类型：mobile - 移动设备，pc - 非移动设备，other - 其它
network	string	网络类型：mobile - 移动网络，broadband - 宽带网络

验证签名

签名的目的在于验证 Webhook 是由小码短链接官方发起的，防止其他人恶意向 Webhook 接口发送伪造的访问数据。

签名验证方式：取 Webhook 签名验证 token（在 API 设置中设置）、短链接 URL、msgid（消息 ID）这三个字段，将它们按字典序排序后拼接成一个字符串，然后进行 SHA1 数字签名，比较所得结果与 sign 字段值是否相等即可。