本页介绍用于在开发阶段测试 webhook 集成的工具与技术，以及在生产环境中排查与调试问题的方法。

​
本地开发

​
暴露本地服务器

由于 Webhook 需要从互联网访问你的服务器，你需要将本地开发服务器对外暴露。

​
使用 Cloudflare Tunnels

Cloudflare Tunnels 提供了一种免费的方式，无需注册账户或打开防火墙端口即可将本地开发服务器安全地暴露到互联网： 
# 从 GitHub Releases 下载 cloudflared，或使用包管理器

# 暴露本地服务器
cloudflared tunnel --url localhost:3000

# 示例输出：
# 已创建临时 Tunnel！访问地址（可能需要一些时间才能可访问）：
# https://abc123.trycloudflare.com
在你的 webhook 配置中使用提供的 URL： 
{
  "url": "https://abc123.trycloudflare.com/webhook"
}

​
常见问题排查

​
Webhook 未到达

  1. 检查 URL 可访问性 – 确保你的端点可从公网访问
  2. 确认 HTTPS – Webhook URL 必须使用 HTTPS
  3. 检查防火墙设置 – 允许外部连接访问你的 webhook 端口
  4. 检查事件过滤 – 确保你订阅了正确的事件类型

​
签名验证失败

  1. 检查密钥 – 确保你使用了正确的 secret
  2. 确认使用原始请求体 – 确保你传入的是原始请求体（raw body）： 
// ❌ 错误——使用了解析后的请求体
const signature = crypto
  .createHmac('sha256', secret)
  .update(JSON.stringify(req.body))
  .digest('hex');

// ✅ 正确——使用原始请求体
app.use('/webhook', express.raw({ type: 'application/json' }));
app.post('/webhook', (req, res) => {
  const signature = crypto
    .createHmac('sha256', secret)
    .update(req.body) // 原始缓冲区
    .digest('hex');
});