> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firecrawl.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 测试

> 对 webhook 进行测试与调试

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

<div id="local-development">
  ## 本地开发
</div>

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

<div id="using-cloudflare-tunnels">
  ### 使用 Cloudflare Tunnels
</div>

[Cloudflare Tunnels](https://github.com/cloudflare/cloudflared/releases) 提供了一种免费的方式，无需打开防火墙端口即可将本地服务器暴露到互联网：

```bash theme={null}
cloudflared tunnel --url localhost:3000
```

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

```json theme={null}
{
  "url": "https://abc123.trycloudflare.com/webhook"
}
```

<div id="troubleshooting">
  ## 故障排查
</div>

<div id="webhooks-not-arriving">
  ### Webhook 未到达
</div>

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

<div id="signature-verification-failing">
  ### 签名验证失败
</div>

最常见的原因是使用了解析后的 JSON 请求体，而不是原始请求体 (raw body) 。另一个原因是使用了错误的 secret，因此请确认它与你的[账户设置](https://www.firecrawl.dev/app/settings?tab=advanced)中的值一致。

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