短链接

Webhook 回调通知使用说明

侯小猴
发布于 2024-08-10 13:13:37

推送机制

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

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

  1. 开通公网可以访问的 IP 地址(或域名)和端口,如果需要对传输加密,请使用支持 HTTPS 的 URL 地址;
  2. 在 API 设置 中设置推送接收 URL ,以及用于签名验证的 token;
  3. 处理 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"
    }
}

参数说明

名称类型描述
scenestring场景值
urlstring短链接
msgidstring消息id
signstring数字签名
recordobject访问记录,详见下文访问记录信息

访问记录信息 record

名称类型描述
idstring访问记录ID
visit_timeinteger访问时间(时间戳,以秒为单位)
new_uvbool是否为新访客
ipstringIP
countrystring国家
regionstring省份
citystring城市
refererstringReferer(空字符串表示直接访问)
browserstring浏览器: wechat - 微信,qq - QQ,tencent - QQ浏览器,sogou - 搜狗浏览器,uc - UC浏览器,ie - IE,edge - Edge, chrome - Chrome,safari - Safari,firefox - Firefox,other - 其它
osstring操作系统:ios/android/windows/mac/linux/other
devicestring设备类型:mobile - 移动设备,pc - 非移动设备
netstring网络类型:mobile - 移动网络,broad - 宽带网络
zstring自定义参数

验证签名

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

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

 

小码至营logo