Webhook イベントタイプ

Firecrawl はジョブのライフサイクルの各段階で webhook イベントを送信するため、ポーリングしなくても進捗を追跡し、結果を取得し、失敗をリアルタイムで処理できます。

クイックリファレンス

Event	Trigger
`crawl.started`	クロールジョブの処理が開始される
`crawl.page`	クロール中にページがスクレイピングされる
`crawl.completed`	クロールジョブが完了し、すべてのページが処理される
`batch_scrape.started`	バッチスクレイプジョブの処理が開始される
`batch_scrape.page`	バッチスクレイプ中にURLがスクレイピングされる
`batch_scrape.completed`	バッチ内のすべてのURLが処理される
`extract.started`	抽出ジョブの処理が開始される
`extract.completed`	抽出が正常に完了する
`extract.failed`	抽出が失敗する
`agent.started`	エージェントジョブの処理が開始される
`agent.action`	エージェントがツール (スクレイピング、検索など) を実行する
`agent.completed`	エージェントが正常に完了する
`agent.failed`	エージェントでエラーが発生する
`agent.cancelled`	エージェントジョブがユーザーによってキャンセルされる
`monitor.page`	監視対象ページのスクレイピングが完了する
`monitor.check.completed`	monitor チェックが完了し、ページ単位の変更を利用できる

ペイロード構造

すべてのWebhookイベントは、この共通の構造を持ちます。

{
  "success": true,
  "type": "crawl.page",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [...],
  "metadata": {}
}

Field	Type	Description
`success`	boolean	操作が成功したかどうか
`type`	string	イベントタイプ (例: `crawl.page`)
`id`	string	ジョブID
`data`	array or object	イベント固有のデータ (下記の例を参照)
`metadata`	object	Webhook 設定で指定したカスタムメタデータ
`error`	string	エラーメッセージ (`success` が `false` の場合)

クロールイベント

`crawl.started`

クロールジョブの処理が開始されるタイミングで送信されます。

{
  "success": true,
  "type": "crawl.started",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [],
  "metadata": {}
}

`crawl.page`

クロール中にスクレイピングされた各ページごとに送信されます。data 配列にはページのコンテンツとメタデータが含まれます。

{
  "success": true,
  "type": "crawl.page",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [
    {
      "markdown": "# Page content...",
      "metadata": {
        "title": "Page 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": "hit",
        "cachedAt": "2025-09-03T21:11:25.636Z",
        "creditsUsed": 1
      }
    }
  ],
  "metadata": {}
}

`crawl.completed`

クロール処理が完了し、すべてのページの処理が終了したときに送信されます。

{
  "success": true,
  "type": "crawl.completed",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [],
  "metadata": {}
}

バッチスクレイプイベント

`batch_scrape.started`

バッチスクレイプジョブの処理開始時に送信されます。

{
  "success": true,
  "type": "batch_scrape.started",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [],
  "metadata": {}
}

`batch_scrape.page`

バッチ内でスクレイプされる各URLごとに送信されます。data 配列にはページコンテンツとメタデータが含まれます。

{
  "success": true,
  "type": "batch_scrape.page",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [
    {
      "markdown": "# Page content...",
      "metadata": {
        "title": "Page 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": {}
}

`batch_scrape.completed`

バッチ内のすべてのURLの処理が完了したときに送信されます。

{
  "success": true,
  "type": "batch_scrape.completed",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [],
  "metadata": {}
}

Monitorイベント

`monitor.page`

監視対象ページのスクレイピングが完了するたびに送信されます。このイベントはスクレイプワーカー経由で発行されるため、monitor check 全体の結果が確定する前に届きます。

monitor.page

{
  "success": true,
  "type": "monitor.page",
  "id": "019df960-5f2a-75fb-a98b-bd2d32ca67d4",
  "webhookId": "f1e2d3c4-0000-0000-0000-000000000000",
  "data": [
    {
      "monitorId": "019df960-06e7-7383-9d89-82c0113dc31a",
      "checkId": "019df960-5f2a-75fb-a98b-bd2d32ca67d4",
      "url": "https://example.com/blog",
      "status": "changed",
      "previousScrapeId": "019df94f-82c3-7e41-81f0-00c72b2d9c52",
      "currentScrapeId": "019df960-73ee-7ac2-97a9-fb0e442c21f1",
      "error": null,
      "isMeaningful": true,
      "judgment": {
        "meaningful": true,
        "confidence": "high",
        "reason": "The page headline changed to announce a new release cadence.",
        "meaningfulChanges": [
          {
            "type": "changed",
            "before": "Welcome to our weekly update.",
            "after": "Welcome to our weekly update — now with daily releases!",
            "reason": "The headline changed in a way that matches the monitor goal."
          }
        ]
      },
      "diff": {
        "text": "--- previous\n+++ current\n@@ -1,3 +1,3 @@\n # Latest posts\n-Welcome to our weekly update.\n+Welcome to our weekly update — now with daily releases!\n"
      }
    }
  ],
  "metadata": {
    "environment": "production"
  }
}

`monitor.check.completed`

monitor のチェックが完了したときに送信されます。data オブジェクトには、チェックの status と集計件数が含まれます。ページ単位の結果は、monitor.page イベントでのみ送信されるか、monitor check API から返されます。

monitor.check.completed

{
  "success": true,
  "type": "monitor.check.completed",
  "id": "019df960-5f2a-75fb-a98b-bd2d32ca67d4",
  "webhookId": "f1e2d3c4-0001-0000-0000-000000000000",
  "data": [
    {
      "monitorId": "019df960-06e7-7383-9d89-82c0113dc31a",
      "checkId": "019df960-5f2a-75fb-a98b-bd2d32ca67d4",
      "status": "completed",
      "summary": {
        "totalPages": 2,
        "same": 1,
        "changed": 1,
        "new": 0,
        "removed": 0,
        "error": 0
      }
    }
  ],
  "metadata": {
    "environment": "production"
  }
}

ページエラーなしでチェックが完了した場合、success は true です。一部のみ完了したチェックまたは失敗したチェックでは、success は false となり、error にメッセージが含まれることがあります。

抽出イベント

`extract.started`

抽出処理が開始されると送信されます。

{
  "success": true,
  "type": "extract.started",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [],
  "metadata": {}
}

`extract.completed`

抽出オペレーションが正常に完了したときに送信されます。data 配列には、抽出されたデータと使用状況情報が含まれます。

{
  "success": true,
  "type": "extract.completed",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [
    {
      "success": true,
      "data": { "siteName": "Example Site", "category": "Technology" },
      "extractId": "550e8400-e29b-41d4-a716-446655440000",
      "llmUsage": 0.0020118,
      "totalUrlsScraped": 1,
      "sources": {
        "siteName": ["https://example.com"],
        "category": ["https://example.com"]
      }
    }
  ],
  "metadata": {}
}

`extract.failed`

抽出処理でエラーが発生したときに送信されます。error フィールドに失敗理由が格納されます。

{
  "success": false,
  "type": "extract.failed",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [],
  "error": "データの抽出に失敗しました：タイムアウトを超過しました",
  "metadata": {}
}

エージェントイベント

/v2/agent で webhook を指定して開始されたジョブに対して送信されます。

`agent.started`

エージェントのジョブの処理が開始されると送信されます。

{
  "success": true,
  "type": "agent.started",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [],
  "metadata": {}
}

`agent.action`

各ツール (scrape、search など) の実行ごとに送信されます。

{
  "success": true,
  "type": "agent.action",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [
    {
      "creditsUsed": 5,
      "action": "mcp__tools__scrape",
      "input": {
        "url": "https://example.com"
      }
    }
  ],
  "metadata": {}
}

action イベントの creditsUsed の値は、これまでに使用されたクレジット総量の推定値です。最終的かつ正確なクレジット数は、completed、failed、cancelled イベントでのみ取得できます。

`agent.completed`

エージェントの処理が正常に完了したときに送信されます。data 配列には、抽出されたデータと消費されたクレジットの合計が含まれます。

{
  "success": true,
  "type": "agent.completed",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [
    {
      "creditsUsed": 15,
      "data": {
        "company": "Example Corp",
        "industry": "Technology",
        "founded": 2020
      }
    }
  ],
  "metadata": {}
}

`agent.failed`

エージェントでエラーが発生したときに送信されます。error フィールドには失敗理由が含まれます。

{
  "success": false,
  "type": "agent.failed",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [
    {
      "creditsUsed": 8
    }
  ],
  "error": "最大クレジット数を超過しました",
  "metadata": {}
}

`agent.cancelled`

ユーザーがエージェントジョブをキャンセルしたときに送信されます。

{
  "success": false,
  "type": "agent.cancelled",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [
    {
      "creditsUsed": 3
    }
  ],
  "metadata": {}
}

イベントのフィルタリング

デフォルトではすべてのイベントを受信します。特定のイベントだけを受信したい場合は、Webhook の設定で events 配列を指定してください。

{
  "url": "https://your-app.com/webhook",
  "events": ["completed", "failed"]
}

ジョブの完了だけ分かればよく、ページ単位の更新は不要な場合に便利です。

はじめに

主要エンドポイント

その他

クイックスタート

開発者ガイド

webhook

ユースケース

その他

貢献

イベントタイプ

クイックリファレンス

ペイロード構造

クロールイベント

`crawl.started`

`crawl.page`

`crawl.completed`

バッチスクレイプイベント

`batch_scrape.started`

`batch_scrape.page`

`batch_scrape.completed`

Monitorイベント

`monitor.page`

`monitor.check.completed`

抽出イベント

`extract.started`

`extract.completed`

`extract.failed`

エージェントイベント

`agent.started`

`agent.action`

`agent.completed`

`agent.failed`

`agent.cancelled`

イベントのフィルタリング

​クイックリファレンス

​ペイロード構造

​クロールイベント

​crawl.started

​crawl.page

​crawl.completed

​バッチスクレイプイベント

​batch_scrape.started

​batch_scrape.page

​batch_scrape.completed

​Monitorイベント

​monitor.page

​monitor.check.completed

​抽出イベント

​extract.started

​extract.completed

​extract.failed

​エージェント イベント

​agent.started

​agent.action

​agent.completed

​agent.failed

​agent.cancelled

​イベントのフィルタリング

クイックリファレンス

ペイロード構造

クロールイベント

`crawl.started`

`crawl.page`

`crawl.completed`

バッチスクレイプイベント

`batch_scrape.started`

`batch_scrape.page`

`batch_scrape.completed`

Monitorイベント

`monitor.page`

`monitor.check.completed`

抽出イベント

`extract.started`

`extract.completed`

`extract.failed`

エージェントイベント

`agent.started`

`agent.action`

`agent.completed`

`agent.failed`

`agent.cancelled`

イベントのフィルタリング