> ## 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.

# 概览

> 为你的 Firecrawl 操作提供实时通知

在爬取、批量抓取、提取、代理任务或监控检查开始、进行或完成时立即收到通知。你无需主动轮询状态，只需提供一个 HTTPS 端点，Firecrawl 就会将事件实时投递到该端点。

<div id="supported-operations">
  ## 支持的操作
</div>

| 操作   | 事件                                                      |
| ---- | ------------------------------------------------------- |
| 爬取   | `started`, `page`, `completed`                          |
| 批量抓取 | `started`, `page`, `completed`                          |
| 提取   | `started`, `completed`, `failed`                        |
| 代理   | `started`, `action`, `completed`, `failed`, `cancelled` |
| 监控   | `check.completed`                                       |

请参见[事件类型](/zh/webhooks/events)以查看完整的 payload 详情和示例。

<div id="configuration">
  ## 配置
</div>

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

```json JSON theme={null}
{
  "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  | 否  | 要接收的事件类型 (默认：全部) |

<div id="usage">
  ## 用法
</div>

<div id="crawl-with-webhook">
  ### 通过 Webhook 爬取
</div>

```bash cURL theme={null}
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"]
      }
    }'
```

<div id="batch-scrape-with-webhook">
  ### 通过 Webhook 进行批量抓取
</div>

```bash cURL theme={null}
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"]
      }
    }'
```

<div id="timeouts-retries">
  ## 超时与重试
</div>

你的 endpoint 必须在 **10 秒** 内返回 `2xx` 状态码。

如果发送失败 (超时、非 2xx 状态码或网络错误) ，Firecrawl 会自动重试：

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

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