本页介绍 Firecrawl 可发送到您端点的各类 webhook 事件。每种事件类型对应您抓取任务的不同阶段。

​
事件结构

所有 webhook 事件均采用以下基础结构： 
{
  "success": true,
  "type": "crawl.page",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [...],
  "metadata": {}
}

​
通用字段

字段类型描述
successboolean操作是否成功
typestring事件类型标识符
idstring作业的唯一标识符
dataarray事件特定数据（因事件类型而异）
metadataobject来自你的 webhook 配置的自定义元数据
errorstring错误信息（当 success 为 false 时存在）

​
爬取事件

沿链接进行的多页面爬取操作。

​
crawl.started

在爬取任务开始时发送。 
{
  "success": true,
  "type": "crawl.started",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [],
  "metadata": {}
}

​
crawl.page

在爬取过程中，每抓取到一个页面就会发送此事件。 
{
  "success": true,
  "type": "crawl.page",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [
    {
      "markdown": "# 欢迎访问我们的网站\n\n这是本页的主要内容……",
      "metadata": {
        "title": "页面标题",
        "description": "页面说明",
        "url": "https://example.com/page",
        "statusCode": 200,
        "contentType": "text/html",
        "scrapeId": "550e8400-e29b-41d4-a716-446655440001",
        "sourceURL": "https://example.com/page",
        "proxyUsed": "basic",
        "cacheState": "命中"
        "cachedAt": "2025-09-03T21:11:25.636Z",
        "creditsUsed": 1
      }
    }
  ],
  "metadata": {}
}
这是爬取过程中最常见的事件。每成功抓取一个页面，你都会收到一个 crawl.page 事件。

​
crawl.completed

在整个爬取操作成功完成时发送。 
{
  "success": true,
  "type": "crawl.completed",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [],
  "metadata": {}
}

​
批量抓取事件

对多个指定 URL 执行抓取的操作。

​
batch_scrape.started

在批量抓取任务开始时发送。 
{
  "success": true,
  "type": "batch_scrape.started",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [],
  "metadata": {}
}

​
batch_scrape.page

针对批处理中每个被抓取的单个 URL 发送。 
{
  "success": true,
  "type": "batch_scrape.page",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [
    {
      "markdown": "# 公司首页\n\n欢迎访问我们的公司网站...",
      "metadata": {
        "title": "公司名称 - 首页",
        "description": "公司简介与总览",
        "url": "https://example.com",
        "statusCode": 200,
        "contentType": "text/html",
        "scrapeId": "550e8400-e29b-41d4-a716-446655440001",
        "sourceURL": "https://example.com",
        "proxyUsed": "basic",
        "cacheState": "miss"
        "cachedAt": "2025-09-03T23:30:53.434Z",
        "creditsUsed": 1
      }
    }
  ],
  "metadata": {}
}
这是批量抓取过程中最常见的事件。每成功抓取一个 URL，你都会收到一个 batch_scrape.page 事件。

​
batch_scrape.completed

在整批抓取操作完成时发送。 
{
  "success": true,
  "type": "batch_scrape.completed",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [],
  "metadata": {}
}

​
提取事件

由 LLM 驱动的数据提取作业。

​
extract.started

当提取操作开始时发送。 
{
  "success": true,
  "type": "extract.started",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [],
  "metadata": {}
}

​
extract.completed

在提取操作成功完成后发送。 
{
  "success": true,
  "type": "extract.completed",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [
    {
      "success": true,
      "data": { "siteName": "示例网站", "category": "科技" },
      "extractId": "550e8400-e29b-41d4-a716-446655440000",
      "llmUsage": 0.0020118,
      "totalUrlsScraped": 1,
      "sources": {
        "siteName": ["https://example.com"],
        "category": ["https://example.com"]
      }
    }
  ],
  "metadata": {}
}

​
extract.failed

当提取操作发生错误时发送。 
{
  "success": false,
  "type": "extract.failed",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [],
  "error": "提取数据失败：超时已超出"
  "metadata": {}
}

​
事件过滤

你可以在 webhook 配置中通过指定 events 数组来控制要接收的事件： 
{
  "url": "https://your-app.com/webhook",
  "events": ["completed", "failed"]
}