Webhooks 让你在 Firecrawl 操作执行过程中实时接收通知。无需轮询状态，当事件发生时，Firecrawl 会自动向你指定的端点发送 HTTP POST 请求。

​
支持的操作

Webhooks 适用于大多数主要的 Firecrawl 操作：
  • Crawl - 在页面被爬取过程中以及爬取完成时收到通知
  • Batch scrape - 针对批量中每个被抓取的 URL 收到更新
  • Extract - 在提取任务开始、完成或失败时收到更新

​
快速开始

在请求中添加 webhook 对象以配置 webhook：
JSON
{
  "webhook": {
    "url": "https://your-domain.com/webhook",
    "metadata": {
      "any_key": "any_value"
    },
    "events": ["started", "page", "completed", "failed"]
  }
}

​
配置选项

字段类型必填描述
urlstring✅你的 webhook 端点 URL
headersobject❌在 webhook 请求中附带的自定义请求头
metadataobject❌附加在所有 webhook 负载中的自定义数据
eventsarray❌要接收的事件类型（默认：全部事件）

​
基本用法示例

​
通过 Webhook 爬取

cURL
curl -X POST https://api.firecrawl.dev/v2/crawl \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -d '{
      "url": "https://docs.firecrawl.dev",
      "limit": 100,
      "webhook": {
        "url": "https://your-domain.com/webhook",
        "metadata": {
          "any_key": "any_value"
        },
        "events": ["started", "page", "completed"]
      }
    }'

​
通过 Webhook 进行批量抓取

cURL
curl -X POST https://api.firecrawl.dev/v2/batch/scrape \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -d '{
      "urls": [
        "https://example.com/page1",
        "https://example.com/page2",
        "https://example.com/page3"
      ],
      "webhook": {
        "url": "https://your-domain.com/webhook",
        "metadata": {
          "any_key": "any_value"
        },
        "events": ["started", "page", "completed"]
      }
    }'

​
处理 Webhook

下面是在你的应用中处理 webhook 的一个简单示例： 
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'));

​
最佳实践

  1. 快速响应 – 始终在 30 秒内返回 2xx 状态码
  2. 异步处理 – 对于耗时任务，将其加入队列并立即返回响应
  3. 验证真实性 – 始终验证 webhook 签名（参见 Security）