Webhook 安全对于确保发送到你端点的请求确实来自 Firecrawl,且未被篡改,至关重要。本页介绍如何验证 webhook 的真实性并落实安全最佳实践。
如果缺乏适当的验证,攻击者可能会:
- 发送伪造的 webhook 请求以触发不必要的 actions
- 篡改负载数据以操纵你的应用
- 通过大量请求使你的 webhook 端点过载
Firecrawl 如何对 Webhook 进行签名
Firecrawl 使用你账户的密钥并通过 HMAC-SHA256 对每个 webhook 请求进行签名。这样会为每个请求生成唯一的签名,以证明:
- 请求来自 Firecrawl
- 有效负载未被篡改
你的 webhook 密钥可在账户设置中的 Advanced 选项卡 找到。每个账户都有一个唯一的密钥,用于为所有 webhook 请求签名。
请妥善保管你的 webhook 密钥,切勿公开泄露。如果你认为
密钥已遭泄露,请立即在账户设置中重新生成。
每个 webhook 请求都会包含一个名为 X-Firecrawl-Signature
的请求头,格式如下:
X-Firecrawl-Signature: sha256=abc123def456...
签名的计算方式如下:
- 取原始请求体(JSON 字符串)
- 使用你的密钥生成 HMAC-SHA256 哈希
- 转为十六进制字符串
- 在前面加上
sha256=
import crypto from 'crypto';
import express from 'express';
const app = express();
// 使用原始请求体解析器进行签名校验
app.use('/webhook/firecrawl', express.raw({ type: 'application/json' }));
app.post('/webhook/firecrawl', (req, res) => {
const signature = req.get('X-Firecrawl-Signature');
const webhookSecret = process.env.FIRECRAWL_WEBHOOK_SECRET;
if (!signature || !webhookSecret) {
return res.status(401).send('未授权');
}
// 从签名头中提取哈希值
const [algorithm, hash] = signature.split('=');
if (algorithm !== 'sha256') {
return res.status(401).send('签名算法无效');
}
// 计算期望的签名
const expectedSignature = crypto
.createHmac('sha256', webhookSecret)
.update(req.body)
.digest('hex');
// 使用恒定时间比较进行签名校验
if (!crypto.timingSafeEqual(Buffer.from(hash, 'hex'), Buffer.from(expectedSignature, 'hex'))) {
return res.status(401).send('签名无效');
}
// 解析并处理已校验的 webhook
const event = JSON.parse(req.body);
console.log('已校验的 Firecrawl webhook:', event);
res.status(200).send('ok');
});
app.listen(3000, () => console.log('监听端口 3000'));
- 从
X-Firecrawl-Signature
头中提取签名
- 获取原始请求体(按收到的原始字节,不要先解析)
- 使用你的密钥和原始请求体计算 HMAC-SHA256
- 使用时间安全的比较函数比较签名
- 仅当签名匹配时才处理该 webhook
切勿信任未经签名验证的 webhook 请求:
// ❌ 不佳 - 未验证
app.post('/webhook', (req, res) => {
processWebhook(req.body); // 危险!
res.status(200).send('OK');
});
// ✅ 良好 - 先验证
app.post('/webhook', (req, res) => {
if (!verifySignature(req)) {
return res.status(401).send('未授权');
}
processWebhook(req.body);
res.status(200).send('OK');
});
标准字符串比较可能泄露时间信息。请使用专用函数:
- Node.js:
crypto.timingSafeEqual()
- Python:
hmac.compare_digest()
- 其他语言:查找“constant-time”或“timing-safe”的比较函数
对 webhook 始终使用 HTTPS 端点:
{
"url": "https://your-app.com/webhook" // ✅ 安全
}
{
"url": "http://your-app.com/webhook" // ❌ 不安全
}