深入理解飞书 Webhook 签名验证：一次踩坑到填坑的完整记录

深入理解飞书 Webhook 签名验证：一次踩坑到填坑的完整记录 | 极客日志

warn: Mud.Feishu.Webhook.FeishuEventValidator[0] 请求头签名验证失败: 计算 +OGVt6ye......, 期望 bc5b503a......

dbug: Mud.Feishu.Webhook.FeishuEventDecryptor[0] 解密成功，结果长度: 489 dbug: Mud.Feishu.Webhook.FeishuEventDecryptor[0] 解密后的JSON数据: {"schema":"2.0","header":{"event_id":"...","token":"fCt8xobp..."}} info: Mud.Feishu.Webhook.FeishuEventDecryptor[0] 事件数据解密成功 - EventType: [contact.department.created_v3]

// 我以为飞书用的是 HMAC-SHA256（因为很多平台都用这个）var signString =$"{timestamp}\n{nonce}\n{body}";usingvar hmac =newHMACSHA256(Encoding.UTF8.GetBytes(encryptKey));var hashBytes = hmac.ComputeHash(Encoding.UTF8.GetBytes(signString));var signature = Convert.ToBase64String(hashBytes);

// 飞书使用的是纯 SHA-256 哈希（不是 HMAC）var signString =$"{timestamp}{nonce}{encryptKey}{body}";usingvar sha256 = SHA256.Create();var hashBytes = sha256.ComputeHash(Encoding.UTF8.GetBytes(signString));var signature = BitConverter.ToString(hashBytes).Replace("-","").ToLower();

特性	HMAC-SHA256	SHA-256
是否需要密钥	✅ 需要（作为 HMAC 的密钥）	❌ 不需要（密钥直接拼接到字符串中）
算法类型	消息认证码	哈希函数
飞书使用	❌	✅
微信使用	✅	❌

// 我以为各部分要用换行符分隔（因为看起来更"规范"）var signString =$"{timestamp}\n{nonce}\n{body}";

// 直接拼接，无任何分隔符var signString =$"{timestamp}{nonce}{encryptKey}{body}";

❌ 错误格式（有换行符，缺少 encryptKey）： 1768550348 149323894 {"encrypt":"Ul/tHTDEQkO..."} ✅ 正确格式（直接拼接，包含 encryptKey）： 1768550348149323894go4kwHmzAbCdEfGhIjKlMnOpQrStUvWx{"encrypt":"Ul/tHTDEQkO..."}

// 我看到解密后的数据里有个 token 字段// {"header":{"token":"fCt8xobpOKdb4yA0UoKJrhNTUaXTzJnf"}}// 我想：这个 token 应该就是用来验证签名的吧？var signString =$"{timestamp}{nonce}{verificationToken}{body}";

密钥类型	用途	在签名验证中
Verification Token	URL 验证请求	❌ 不使用
Encrypt Key	数据加密/解密 + 签名验证	✅ 使用这个

// 我习惯性地把哈希结果转成 Base64var hashBytes = sha256.ComputeHash(Encoding.UTF8.GetBytes(signString));var signature = Convert.ToBase64String(hashBytes);// 结果：lL4qIgAs8Kx... (Base64 格式)

// 转换为小写十六进制字符串var hashBytes = sha256.ComputeHash(Encoding.UTF8.GetBytes(signString));var signature = BitConverter.ToString(hashBytes).Replace("-","").ToLower();// 结果：f2d909fb8a7c... (小写十六进制)

原始哈希值（字节数组）： [242, 217, 9, 251, 138, 124, 62, 29, ...] ❌ Base64 编码： 8tkJ+4p8Ph0... ✅ 小写十六进制： f2d909fb8a7c3e1d...

publicasyncTask<bool>ValidateSignature(long timestamp,string nonce,string body,string headerSignature,string encryptKey){try{// ========== 第 1 步：基础验证 ==========// 检查必要参数if(string.IsNullOrEmpty(headerSignature)){ _logger.LogWarning("请求头中缺少 X-Lark-Signature");returnfalse;}if(timestamp ==0||string.IsNullOrEmpty(nonce)){ _logger.LogWarning("时间戳或 nonce 为空");returnfalse;}// ========== 第 2 步：防重放攻击 ==========// 检查 nonce 是否已使用（需要配合 Redis 等缓存实现）if(awaitIsNonceUsed(nonce)){ _logger.LogWarning("Nonce {Nonce} 已使用过，拒绝重放攻击", nonce);returnfalse;}// 验证时间戳（容错 60 秒）if(!IsTimestampValid(timestamp,toleranceSeconds:60)){ _logger.LogWarning("请求时间戳无效: {Timestamp}", timestamp);returnfalse;}// ========== 第 3 步：构建签名字符串 ==========// 注意：直接拼接，无分隔符var signString =$"{timestamp}{nonce}{encryptKey}{body}";// 调试日志（生产环境建议关闭） _logger.LogDebug("签名字符串前 100 字符: {SignStringPrefix}", signString.Substring(0, Math.Min(100, signString.Length)));// ========== 第 4 步：计算 SHA-256 哈希 ==========usingvar sha256 = SHA256.Create();var hashBytes = sha256.ComputeHash(Encoding.UTF8.GetBytes(signString));// ========== 第 5 步：转换为小写十六进制字符串 ==========var computedSignature = BitConverter.ToString(hashBytes).Replace("-","").ToLower(); _logger.LogDebug("计算的签名: {ComputedSignature}", computedSignature); _logger.LogDebug("期望的签名: {ExpectedSignature}", headerSignature);// ========== 第 6 步：固定时间比较 ==========// 使用固定时间比较防止计时攻击var isValid =FixedTimeEquals(computedSignature, headerSignature);if(isValid){ _logger.LogInformation("签名验证成功");// 标记 nonce 为已使用awaitMarkNonceAsUsed(nonce);}else{ _logger.LogWarning("签名验证失败");}return isValid;}catch(Exception ex){ _logger.LogError(ex,"验证签名时发生错误");returnfalse;}}/// <summary>/// 固定时间比较，防止计时攻击/// </summary>privatestaticboolFixedTimeEquals(string a,string b){if(a.Length != b.Length)returnfalse;var result =0;for(var i =0; i < a.Length; i++){ result |= a[i]^ b[i];}return result ==0;}/// <summary>/// 验证时间戳是否在有效范围内/// </summary>privateboolIsTimestampValid(long timestamp,int toleranceSeconds){var requestTime = DateTimeOffset.FromUnixTimeSeconds(timestamp);var now = DateTimeOffset.UtcNow;var diff = Math.Abs((now - requestTime).TotalSeconds);return diff <= toleranceSeconds;}

import hashlib import time defvalidate_signature(timestamp, nonce, body, header_signature, encrypt_key):"""验证飞书 Webhook 签名"""# 1. 基础验证ifnot header_signature ornot nonce or timestamp ==0:returnFalse# 2. 时间戳验证（容错 60 秒） current_time =int(time.time())ifabs(current_time - timestamp)>60:returnFalse# 3. 构建签名字符串（直接拼接） sign_string =f"{timestamp}{nonce}{encrypt_key}{body}"# 4. 计算 SHA-256 哈希 hash_obj = hashlib.sha256(sign_string.encode('utf-8'))# 5. 转换为小写十六进制 computed_signature = hash_obj.hexdigest().lower()# 6. 比较签名return computed_signature == header_signature.lower()

const crypto =require('crypto');functionvalidateSignature(timestamp, nonce, body, headerSignature, encryptKey){// 1. 基础验证if(!headerSignature ||!nonce ||!timestamp){returnfalse;}// 2. 时间戳验证（容错 60 秒）const currentTime = Math.floor(Date.now()/1000);if(Math.abs(currentTime - timestamp)>60){returnfalse;}// 3. 构建签名字符串（直接拼接）const signString =`${timestamp}${nonce}${encryptKey}${body}`;// 4. 计算 SHA-256 哈希并转换为小写十六进制const computedSignature = crypto .createHash('sha256').update(signString,'utf8').digest('hex').toLowerCase();// 5. 比较签名return computedSignature === headerSignature.toLowerCase();}

1. 黑客截获了一个合法的飞书请求 2. 黑客重复发送这个请求 100 次 3. 你的服务器处理了 100 次相同的事件 4. 💥 业务逻辑被重复执行，造成数据混乱

publicclassNonceDeduplicator{privatereadonlyIDistributedCache _cache;privatereadonlyILogger<NonceDeduplicator> _logger;publicasyncTask<bool>IsNonceUsed(string nonce){var key =$"feishu:nonce:{nonce}";varvalue=await _cache.GetStringAsync(key);returnvalue!=null;}publicasyncTaskMarkNonceAsUsed(string nonce){var key =$"feishu:nonce:{nonce}";var options =newDistributedCacheEntryOptions{// 5 分钟后自动过期（与时间戳容错时间一致） AbsoluteExpirationRelativeToNow = TimeSpan.FromMinutes(5)};await _cache.SetStringAsync(key,"1", options); _logger.LogDebug("Nonce {Nonce} 已标记为已使用", nonce);}}

场景 1：网络延迟 飞书发送时间：14:00:00 到达你服务器：14:00:05 ✅ 5 秒延迟，可以接受 场景 2：恶意攻击 飞书发送时间：14:00:00 黑客重放时间：15:00:00 ❌ 1 小时延迟，明显异常

环境	建议容错时间	原因
生产环境	60 秒	平衡安全性和可用性
测试环境	300 秒	方便调试
开发环境	600 秒	本地时间可能不准

publicboolIsTimestampValid(long timestamp,int toleranceSeconds =60){// 飞书的时间戳是秒级的var requestTime = DateTimeOffset.FromUnixTimeSeconds(timestamp);var now = DateTimeOffset.UtcNow;// 计算时间差（绝对值）var diff = Math.Abs((now - requestTime).TotalSeconds);if(diff > toleranceSeconds){ _logger.LogWarning("时间戳超出容错范围: 请求时间 {RequestTime}, 当前时间 {CurrentTime}, 差异 {Diff}秒", requestTime, now, diff);returnfalse;}returntrue;}

// 千万不要这样做！publicclassFeishuConfig{publicconststring EncryptKey ="go4kwHmzAbCdEfGhIjKlMnOpQrStUvWx";publicconststring VerificationToken ="fCt8xobpOKdb4yA0UoKJrhNTUaXTzJnf";}

// appsettings.json（不包含敏感信息）{"FeishuWebhook":{"RoutePrefix":"feishu/webhook"}}// 环境变量（在服务器上配置） FEISHU_ENCRYPT_KEY=go4kwHmzAbCdEfGhIjKlMnOpQrStUvWx FEISHU_VERIFICATION_TOKEN=fCt8xobpOKdb4yA0UoKJrhNTUaXTzJnf // 代码中读取var encryptKey = Environment.GetEnvironmentVariable("FEISHU_ENCRYPT_KEY");

// 使用 Azure Key Vaultvar client =newSecretClient(vaultUri,newDefaultAzureCredential());var secret =await client.GetSecretAsync("feishu-encrypt-key");var encryptKey = secret.Value.Value;// 使用 AWS Secrets Managervar client =newAmazonSecretsManagerClient();var request =newGetSecretValueRequest{ SecretId ="feishu/encrypt-key"};var response =await client.GetSecretValueAsync(request);var encryptKey = response.SecretString;

{"FeishuWebhook":{"MultiAppEncryptKeys":{"cli_a98ea7d1a0ba100b":"go4kwHmzAbCdEfGhIjKlMnOpQrStUvWx","cli_b12345678901234c":"xY9zAbCdEfGhIjKlMnOpQrStUvWx1234","cli_c98765432109876d":"1234AbCdEfGhIjKlMnOpQrStUvWxYz56"},"DefaultAppId":"cli_a98ea7d1a0ba100b"}}

privatestringGetEncryptKey(string appId){// 尝试从多应用配置中获取if(_options.MultiAppEncryptKeys.TryGetValue(appId,outvar key)){ _logger.LogDebug("使用应用 {AppId} 的专用密钥", appId);return key;}// 回退到默认密钥if(!string.IsNullOrEmpty(_options.DefaultAppId)&& _options.MultiAppEncryptKeys.TryGetValue(_options.DefaultAppId,outvar defaultKey)){ _logger.LogWarning("未找到应用 {AppId} 的密钥，使用默认密钥", appId);return defaultKey;}// 最后回退到主密钥 _logger.LogWarning("使用主密钥");return _options.EncryptKey;}

_logger.LogDebug("========== 签名验证调试信息 =========="); _logger.LogDebug("Timestamp: {Timestamp}", timestamp); _logger.LogDebug("Nonce: {Nonce}", nonce); _logger.LogDebug("Encrypt Key 前 8 位: {KeyPrefix}", encryptKey.Substring(0,8)); _logger.LogDebug("Body 长度: {BodyLength}", body.Length); _logger.LogDebug("Body 前 100 字符: {BodyPrefix}", body.Substring(0, Math.Min(100, body.Length))); _logger.LogDebug("签名字符串前 150 字符: {SignStringPrefix}", signString.Substring(0, Math.Min(150, signString.Length))); _logger.LogDebug("计算的签名: {ComputedSignature}", computedSignature); _logger.LogDebug("期望的签名: {ExpectedSignature}", headerSignature); _logger.LogDebug("========================================");

<!DOCTYPEhtml><html><head><title>飞书签名验证工具</title><scriptsrc="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/4.1.1/crypto-js.min.js"></script></head><body><h1>飞书签名验证工具</h1><label>Timestamp:</label><inputtype="text"id="timestamp"placeholder="1768550348"><br><label>Nonce:</label><inputtype="text"id="nonce"placeholder="149323894"><br><label>Encrypt Key:</label><inputtype="text"id="encryptKey"placeholder="32位密钥"><br><label>Body:</label><textareaid="body"rows="5"placeholder='{"encrypt":"..."}'></textarea><br><buttononclick="calculate()">计算签名</button><h3>结果：</h3><divid="result"></div><script>functioncalculate(){const timestamp = document.getElementById('timestamp').value;const nonce = document.getElementById('nonce').value;const encryptKey = document.getElementById('encryptKey').value;const body = document.getElementById('body').value;// 构建签名字符串const signString = timestamp + nonce + encryptKey + body;// 计算 SHA-256const hash = CryptoJS.SHA256(signString);const signature = hash.toString(CryptoJS.enc.Hex).toLowerCase();// 显示结果 document.getElementById('result').innerHTML =` <p><strong>签名字符串前 100 字符：</strong><br> ${signString.substring(0,100)}...</p> <p><strong>计算的签名：</strong><br> <code>${signature}</code></p> `;}</script></body></html>

[Fact]publicasyncTaskValidateSignature_WithCorrectData_ShouldReturnTrue(){// Arrangevar timestamp =1768550348L;var nonce ="149323894";var encryptKey ="go4kwHmzAbCdEfGhIjKlMnOpQrStUvWx";var body ="{\"encrypt\":\"Ul/tHTDEQkOlKZuqYTS7t...\"}";// 手动计算期望的签名var signString =$"{timestamp}{nonce}{encryptKey}{body}";usingvar sha256 = SHA256.Create();var hashBytes = sha256.ComputeHash(Encoding.UTF8.GetBytes(signString));var expectedSignature = BitConverter.ToString(hashBytes).Replace("-","").ToLower();// Actvar result =await _validator.ValidateSignature( timestamp, nonce, body, expectedSignature, encryptKey);// Assert Assert.True(result);}

错误现象	可能原因	解决方案	优先级
签名不匹配	使用了 HMAC-SHA256	改用纯 SHA-256	⭐⭐⭐
签名不匹配	签名字符串有换行符	直接拼接，无分隔符	⭐⭐⭐
签名不匹配	使用了 Verification Token	改用 Encrypt Key	⭐⭐⭐
签名不匹配	输出格式为 Base64	改用小写十六进制	⭐⭐⭐
签名不匹配	签名字符串缺少 Encrypt Key	添加 Encrypt Key	⭐⭐⭐
时间戳无效	服务器时间不同步	同步服务器时间	⭐⭐
Nonce 重复	Redis 缓存配置错误	检查 Redis 连接	⭐⭐
解密成功但签名失败	密钥配置混乱	确认使用正确的密钥	⭐⭐

平台	签名算法	密钥类型	字符串格式	输出格式	分隔符
飞书	SHA-256	Encrypt Key	timestamp+nonce+key+body	小写 Hex	无
微信	SHA-1	Token	字典序排序后拼接	小写 Hex	无
钉钉	HMAC-SHA256	App Secret	timestamp+\n+secret	Base64	\n
企业微信	SHA-256	Token	字典序排序后拼接	小写 Hex	无
Slack	HMAC-SHA256	Signing Secret	version:timestamp:body	Hex	:

// 好的日志示例 _logger.LogDebug("签名字符串: {SignString}", signString); _logger.LogDebug("计算的签名: {Computed}, 期望的签名: {Expected}", computed, expected);// 不好的日志示例 _logger.LogError("签名验证失败");// 没有任何有用信息

var toleranceSeconds = _environment.IsProduction()?60:300;

[Theory][InlineData(1768550348,"149323894","go4kwHmz...","{...}","f2d909fb...")]publicasyncTaskValidateSignature_WithKnownData_ShouldMatch(long timestamp,string nonce,string key,string body,string expected){var result =await _validator.ValidateSignature( timestamp, nonce, body, expected, key); Assert.True(result);}

publicasyncTask<bool>ValidateFeishuSignature(HttpRequest request){// 1. 提取请求头var timestamp =long.Parse(request.Headers["X-Lark-Request-Timestamp"]);var nonce = request.Headers["X-Lark-Request-Nonce"].ToString();var signature = request.Headers["X-Lark-Signature"].ToString();// 2. 读取请求体 request.EnableBuffering();var body =awaitnewStreamReader(request.Body).ReadToEndAsync(); request.Body.Position =0;// 3. 构建签名字符串var signString =$"{timestamp}{nonce}{_encryptKey}{body}";// 4. 计算 SHA-256usingvar sha256 = SHA256.Create();var hash = sha256.ComputeHash(Encoding.UTF8.GetBytes(signString));var computed = BitConverter.ToString(hash).Replace("-","").ToLower();// 5. 比较签名return computed == signature;}

{"FeishuWebhook":{"VerificationToken":"从飞书后台获取","EncryptKey":"从飞书后台获取（32位）","RoutePrefix":"feishu/webhook","TimestampToleranceSeconds":60,"EnableRequestLogging":true,"EnableBackgroundProcessing":false}}

术语	英文	解释
签名	Signature	用于验证数据完整性和来源的字符串
哈希	Hash	将任意长度数据转换为固定长度的算法
HMAC	Hash-based Message Authentication Code	基于哈希的消息认证码
Nonce	Number used once	一次性随机数，用于防重放攻击
时间戳	Timestamp	Unix 时间戳，表示请求发送时间
重放攻击	Replay Attack	重复发送已截获的合法请求
计时攻击	Timing Attack	通过测量操作时间来推断信息

深入理解飞书 Webhook 签名验证：一次踩坑到填坑的完整记录

故事的开始：一个神秘的签名验证失败

问题现场

初步分析

飞书 Webhook 的安全机制

两把钥匙的故事

飞书发送请求的完整流程

你的服务器需要做什么

我踩过的四个大坑

坑 #1：用错了签名算法

❌ 我最初的错误实现

✅ 正确的实现

坑 #2：签名字符串格式错误

❌ 我最初的错误实现

✅ 正确的实现

坑 #3：用错了密钥

❌ 我曾经的困惑

✅ 正确的理解

坑 #4：输出格式不对

❌ 我最初的错误实现

✅ 正确的实现

正确的实现方式

完整的验证流程

C# 完整代码实现

其他语言实现参考

Python 实现

JavaScript/Node.js 实现

安全防护的艺术

防重放攻击：Nonce 去重机制

什么是重放攻击？

如何防止？

代码实现（使用 Redis）

防重放攻击：时间戳验证

为什么需要时间戳验证？

容错时间设置建议

代码实现

防重放攻击：密钥管理

❌ 危险的做法

✅ 安全的做法

防重放攻击：多应用场景

配置文件

代码实现

问题排查指南

排查清单

排查技巧

技巧 1：打印关键信息

技巧 2：使用在线工具验证

技巧 3：单元测试

排查速查表

总结与思考

核心要点回顾

对比其他平台

排查经验总结

💡 经验 1：不要想当然

💡 经验 2：日志是你最好的朋友

💡 经验 3：安全性和可用性的平衡

💡 经验 4：写单元测试

延伸思考

🤔 为什么飞书不用 HMAC-SHA256？

🤔 为什么要把密钥放在签名字符串里？

推 荐 资 源

📚 官方文档

🛠️ 开源项目

写在最后

附录：快速参考

A. 签名验证代码模板（C#）

B. 配置文件模板

C. 术语表

微信扫一扫，关注极客日志

更多推荐文章

相关免费在线工具

推荐资源