イベントタイプ

Webhook イベントリファレンス

​

ペイロード構造

すべての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	イベント固有のデータ（下記の例を参照）
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": {}
}

​

抽出イベント

​

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": {}
}

​

エージェントイベント

​

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"]
}

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