测试

对 webhook 进行测试与调试

在部署到生产环境之前，请先确认你的 webhook 集成能够正常工作。本页介绍如何在本地机器上接收 webhook，以及如何排查常见的投递和验证失败问题。

​

本地开发

由于 Webhook 需要一个可公开访问的 URL，你需要在开发期间将本地服务器对外暴露。

​

使用 Cloudflare Tunnels

Cloudflare Tunnels 提供了一种免费的方式，无需打开防火墙端口即可将本地服务器暴露到互联网：

cloudflared tunnel --url localhost:3000

你会获得一个类似 https://abc123.trycloudflare.com 的公网 URL。在你的 webhook 配置中使用该地址：

{
  "url": "https://abc123.trycloudflare.com/webhook"
}

​

故障排查

​

Webhook 未到达

• 端点不可访问 - 确认你的服务器可以被公网访问，并且防火墙允许入站连接
• 使用 HTTP - Webhook URL 必须使用 HTTPS
• 事件配置错误 - 检查 webhook 配置中的 events 过滤器
• 超时错误 - 确保你的端点在 10 秒内响应

​

签名验证失败

最常见的原因是使用了解析后的 JSON 请求体，而不是原始请求体 (raw body) 。另一个原因是使用了错误的 secret，因此请确认它与你的账户设置中的值一致。

// ❌ 错误——使用了解析后的请求体
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');
});