Webhooks | Firecrawl

Webhooks 让你能够随着操作进展实时接收通知，而无需主动轮询状态。

支持的操作

操作	事件
Crawl	`started`, `page`, `completed`
Batch Scrape	`started`, `page`, `completed`
Extract	`started`, `completed`, `failed`
Agent	`started`, `action`, `completed`, `failed`, `cancelled`

配置

在你的请求中添加一个 webhook 对象：

JSON

{
  "webhook": {
    "url": "https://your-domain.com/webhook",
    "metadata": {
      "any_key": "any_value"
    },
    "events": ["started", "page", "completed", "failed"]
  }
}

字段	类型	必填	描述
`url`	string	是	你的端点 URL（HTTPS）
`headers`	object	否	要附带的自定义请求头
`metadata`	object	否	包含在负载中的自定义数据
`events`	array	否	要接收的事件类型（默认：全部）

用法

通过 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"]
      }
    }'

超时与重试

你的 endpoint 必须在 10 秒 内返回 2xx 状态码。如果发送失败（超时、非 2xx 状态码或网络错误），Firecrawl 会自动重试：

重试次数	失败后的延迟时间
第 1 次	1 分钟
第 2 次	5 分钟
第 3 次	15 分钟

在 3 次重试均失败后，该 webhook 会被标记为失败，不再进行后续尝试。

快速上手

新功能

核心功能

开发者指南

Webhook 回调

使用场景

参与贡献

概览

支持的操作

配置

用法

通过 Webhook 爬取

通过 Webhook 进行批量抓取

超时与重试

​支持的操作

​配置

​用法

​通过 Webhook 爬取

​通过 Webhook 进行批量抓取

​超时与重试

支持的操作

配置

用法

通过 Webhook 爬取

通过 Webhook 进行批量抓取

超时与重试