如何使用密钥验证Bitbucket Webhook签名？

核心排查与修复步骤 #

• 获取原始请求体
  Bitbucket的签名基于未修改的原始请求体字节流生成，若提前用$_POST或框架自动解析过请求体，php://input将无法读取到正确的原始内容。正确获取方式：

  $payload = file_get_contents('php://input');
  

• 核对密钥一致性
  确保代码中使用的密钥与Bitbucket Webhook配置中的密钥完全一致，注意大小写、空格、特殊字符，不要做任何修改或截断。你的示例密钥q3bn5JCdR1yqK46V需原样使用。

• 正确生成并验证签名
  你的代码逻辑框架正确，但需使用安全的哈希比较方式避免时序攻击。完整验证代码：

  $secret = 'q3bn5JCdR1yqK46V';
  $payload = file_get_contents('php://input');
  $expectedSignature = $_SERVER['HTTP_X_HUB_SIGNATURE_256'];
  
  $generatedSignature = 'sha256=' . hash_hmac('sha256', $payload, $secret);
  
  // 用hash_equals做安全比较
  if (hash_equals($generatedSignature, $expectedSignature)) {
      // 验证通过，执行部署逻辑
  } else {
      // 验证失败，拒绝请求
  }
  

• 确认请求头获取正确
  在PHP环境中，X-Hub-Signature-256请求头对应的服务器变量是$_SERVER['HTTP_X_HUB_SIGNATURE_256']，确保变量名拼写正确，无大小写错误。

• 排除字符集干扰
  确保服务器PHP环境的default_charset设置为UTF-8，避免对请求体做自动编码转换，导致签名计算的基础数据不一致。

内容的提问来源于stack exchange，提问作者Gustavo Soares