Webhook 签名:钉钉、企业微信、飞书的四种算法差异
Alioth 技术笔记 · 第 13 篇 · 通知 / 集成 仓库:github.com/aide-family… | 在线演示:web.alioth.asia/
导语
"接一个 Webhook"听起来是一个 POST 请求的事,直到你发现钉钉把签名放在查询参数里、飞书放在请求体里、用自定义通道时又想自己定一套头。更麻烦的是时间戳单位:钉钉要毫秒、飞书要秒,差一个数量级就是"签名不匹配"。Alioth 把这些差异全部封装在 sender 里,任务表只存渠道类型、应用类型和密钥。这篇把四个实现摆在一起对比。
一、四个 sender,一张对比表
| 通道 | 时间戳单位 | 签名位置 | 参与签名的内容 | 编码 |
|---|---|---|---|---|
| OTHER(自定义) | 秒 | 请求头 | timestamp + "." + body | hex + sha256= 前缀 |
| 钉钉 | 毫秒 | URL 查询参数 | timestamp + "\n" + secret(secret 作 HMAC key) | base64 |
| 企业微信 | — | 无签名 | 密钥就在 Webhook URL 里 | — |
| 飞书 | 秒 | 请求体字段 | timestamp + "\n" + secret 作为密钥,消息为空 | base64 |
四种排在一起,能立刻看出为什么不能写一份"通用签名":单位、位置、参与内容、编码方式,四个维度全都不同。
二、自定义通道:可预期的一套
headers := map[string]string{}
if task.ChannelSecret != "" {
timestamp := strconv.FormatInt(time.Now().Unix(), 10)
headers["X-Alioth-Timestamp"] = timestamp
headers["X-Alioth-Signature"] = "sha256=" + hex.EncodeToString(
hmacSHA256([]byte(task.ChannelSecret), []byte(timestamp+"."+string(payload))),
)
}
这套设计对接收方最友好:时间戳和签名都在头里,正文保持原样,验签方不需要先解析 JSON。timestamp + "." + payload 的拼接方式避免了"时间戳和正文边界不清"导致的伪造——虽然实际意义不大,但比裸拼接更严谨。
三、钉钉:签名在 URL 上,时间戳是毫秒
timestamp := time.Now().UnixMilli()
values := url.Values{}
values.Set("timestamp", strconv.FormatInt(timestamp, 10))
values.Set("sign", dingTalkSign(task.ChannelSecret, timestamp))
endpoint = appendQuery(endpoint, values)
func dingTalkSign(secret string, timestamp int64) string {
stringToSign := fmt.Sprintf("%d\n%s", timestamp, secret)
mac := hmac.New(sha256.New, []byte(secret)) // secret 是 key
mac.Write([]byte(stringToSign)) // "ts\nsecret" 是消息
return base64.StdEncoding.EncodeToString(mac.Sum(nil))
}
三个细节容易错:毫秒(UnixMilli)、签名要 URL 编码后拼进 query(appendQuery 用 url.Values 完成转义)、StringToSign 是 timestamp + "\n" + secret 而密钥是 secret 本身。漏掉换行、用秒、或者把 secret 当消息,都会得到 310000 签名不匹配。
四、企业微信:其实没有签名
企业微信的群机器人把密钥直接编进了 Webhook URL(?key=...),所以发消息时不需要额外签名:
payload := map[string]any{"msgtype": "text", "text": map[string]string{"content": webhookText(subject, body)}}
data, err := postJSON(ctx, task.ChannelEndpoint, payload)
但"没有签名"不等于"可以忽略响应"。企业微信和钉钉一样,HTTP 200 也可能返回 errcode != 0,所以必须解析响应体:
if reply.ErrCode != 0 {
return fmt.Errorf("wechat errcode %d: %s", reply.ErrCode, reply.ErrMsg)
}
只判断 HTTP 状态码,会把"机器人被移出群聊"当成发送成功。
五、飞书:签名在请求体,密钥是拼接后的字符串
timestamp := time.Now().Unix() // 秒
payload["timestamp"] = strconv.FormatInt(timestamp, 10)
payload["sign"] = feishuSign(task.ChannelSecret, timestamp)
func feishuSign(secret string, timestamp int64) string {
stringToSign := strconv.FormatInt(timestamp, 10) + "\n" + secret
mac := hmac.New(sha256.New, []byte(stringToSign)) // 拼接串是 key
// 消息为空
return base64.StdEncoding.EncodeToString(mac.Sum(nil))
}
这是四种里最反直觉的一个:密钥不是 secret,而是 timestamp + "\n" + secret;被签名的消息是空字符串。很多人按"用 secret 签 timestamp"的直觉去实现,结果永远验不过。而且飞书的 timestamp/sign 放在 JSON body 里,不是头、也不是 query。
响应校验也要看两个字段:code 和 StatusCode,任一非 0 都算失败。
六、为什么签名在 sender 里,不在任务表里
任务表存的是 channel_type、channel_app、channel_secret、channel_endpoint,签名是发送那一刻才算出来的。原因很简单:签名带时间戳,而任务可能在队列里等几十秒、重试三次。提前算好签名,等于发出去的时候已经过期。
这也是 senderFor 存在的意义:
switch kind {
case "SMTP": return smtpSender{}, nil
case "WEBHOOK":
switch app {
case "OTHER": return otherSender{}, nil
case "DINGTALK": return dingTalkSender{}, nil
case "WECHAT": return wechatSender{}, nil
case "FEISHU": return feishuSender{}, nil
}
}
四个实现各自处理签名、payload 形状、响应解析,任务层完全不感知。新增一个厂商只需要加一个 sender 和一个枚举,不改任务表和重试逻辑。
payload 形状也是三套:钉钉和企业微信是 msgtype + text.content,飞书是 msg_type + content.text。webhookText 统一把标题和正文拼成 subject + "\n" + body,所以用户在模板里写不写标题都能得到可读的两行文本。差一个下划线、少一层嵌套,厂商就会返回 400 或业务错误码——这类错误没有任何编译期保护,只能靠每个 sender 自己的解析与断言。
七、网络层的三个防御
postRaw 是所有 sender 的公共出口,做了三件事:
if parsed.Host == "" || (parsed.Scheme != "http" && parsed.Scheme != "https") {
return nil, fmt.Errorf("invalid webhook endpoint")
}
...
data, err := io.ReadAll(io.LimitReader(resp.Body, maxWebhookResponse+1))
if len(data) > maxWebhookResponse {
return nil, fmt.Errorf("webhook response is too large")
}
if resp.StatusCode >= 300 {
return nil, fmt.Errorf("webhook status %d: %s", resp.StatusCode, truncate(string(data), 200))
}
- 只允许 http/https 且有 host:防止配置成
file://或空地址; - 响应体上限 64KB:一个恶意的或配置错误的地址可能返回巨大响应,把内存打满;
- 错误信息截断到 200 字符:状态码错误会把响应体带进错误详情,不截断可能把整页 HTML 写进消息日志。
另外全局 webhookClient 超时 30 秒,和通知任务 3 次重试配合:一次超时不会拖住整轮投递。
需要说清楚的边界:这三条防的是配置错误,不是 SSRF。Endpoint 由租户管理员填写,属于可信配置面;如果将来允许更低权限的角色配置 Webhook,就必须补上私网地址与元数据端点的拦截。代码里的校验只保证"这是一个能发的 HTTP 地址",不保证"这个地址是安全的"——把这两件事混为一谈,是很多 Webhook 功能上线后才发现的问题。
八、几个真实的坑
- HTTP 200 + 业务错误码。 钉钉、企业微信、飞书都会用 200 返回
errcode != 0,只判状态码等于把失败当成功。 truncate按字节截断。 这里是value[:limit],如果响应是中文,截断处可能出现半个 UTF-8 字符。错误信息只用于展示,影响有限,但要知道这是字节级操作。- 签名必须用请求体的最终字节**。** 自定义通道的签名是对
payload(序列化后的 JSON)算的,如果中间又改了一次序列化(比如 map 顺序变化),签名就对不上。代码里payload只 marshal 一次,签名和发送共用同一个[]byte。 - 应用类型决定 payload 形状。 钉钉/企微是
msgtype + text.content,飞书是msg_type + content.text,差一个下划线就是 400。
九、怎么验证
app/merak/internal/biz/notify/sender_webhook_test.go 覆盖了四种签名算法与业务错误码解析。其中 TestFeishuSignUsesEmptyMessage 值得单独一提:它用固定向量断言"key 是 timestamp\nsecret、消息为空",把这个反直觉的算法钉成回归测试——这类实现如果只靠"能发出去"来验证,换个人重构时几乎一定会被改成"用 secret 签 timestamp"。手工验证最快的方式是起一个本地回显服务:
git clone https://github.com/aide-family/moon.git && cd moon
make dev-up
open http://127.0.0.1:8080
用 nc -l 9999 或任意 HTTP 回显工具接住请求,分别配四种渠道类型,对比收到的 query/header/body:钉钉应该多出 timestamp(13 位)和 sign,飞书的 body 里应该多出 timestamp 和 sign,企业微信两边都没有签名,自定义通道则应该看到两个 X-Alioth-* 头。
结语
Webhook 集成的复杂度不在 HTTP 本身,而在每家厂商对"签名"有自己的理解:签什么、放哪里、用什么单位、最后怎么编码。Alioth 的选择是把这些差异全部关进 sender:任务层只关心"发哪一个渠道、用哪套凭据",签名的时效性和算法细节由发送方在最后一刻计算。这样新增厂商时,变的只是一个小文件,而不是整条投递链路。
下一篇:Kubernetes 多集群接入——kubeconfig 加密、context 探测与危险的凭据拒绝。