This page covers all the different types of webhook events that Firecrawl can send to your endpoint. Each event type corresponds to a different stage in your scraping operations.

​
Event Structure

All webhook events follow this basic structure: 
{
  "success": true,
  "type": "crawl.page",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [...],
  "metadata": {}
}

​
Common Fields

FieldTypeDescription
successbooleanWhether the operation was successful
typestringEvent type identifier
idstringUnique identifier for the job
dataarrayEvent-specific data (varies by event type)
metadataobjectCustom metadata from your webhook configuration
errorstringError message (present when success is false)

​
Crawl Events

Multi-page crawling operations that follow links.

​
crawl.started

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

​
crawl.page

Sent for each individual page that gets scraped during a crawl. 
{
  "success": true,
  "type": "crawl.page",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [
    {
      "markdown": "# Welcome to our website\n\nThis is the main content of the page...",
      "metadata": {
        "title": "Page Title",
        "description": "Page 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": {}
}
This is the most frequent event during crawls. You’ll receive one crawl.page event for every page successfully scraped.

​
crawl.completed

Sent when the entire crawl operation finishes successfully. 
{
  "success": true,
  "type": "crawl.completed",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [],
  "metadata": {}
}

​
Batch Scrape Events

Operations that scrape multiple specific URLs.

​
batch_scrape.started

Sent when a batch scrape operation begins. 
{
  "success": true,
  "type": "batch_scrape.started",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [],
  "metadata": {}
}

​
batch_scrape.page

Sent for each individual URL that gets scraped in the batch. 
{
  "success": true,
  "type": "batch_scrape.page",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [
    {
      "markdown": "# Company Homepage\n\nWelcome to our company website...",
      "metadata": {
        "title": "Company Name - Homepage",
        "description": "Company description and overview",
        "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": {}
}
This is the most frequent event during batch scrapes. You’ll receive one batch_scrape.page event for every URL successfully scraped.

​
batch_scrape.completed

Sent when the entire batch scrape operation finishes. 
{
  "success": true,
  "type": "batch_scrape.completed",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [],
  "metadata": {}
}

​
Extract Events

LLM-powered data extraction operations.

​
extract.started

Sent when an extract operation begins. 
{
  "success": true,
  "type": "extract.started",
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "data": [],
  "metadata": {}
}

​
extract.completed

Sent when an extract operation finishes successfully. 
{
  "success": true,
  "type": "extract.completed",
  "jobId": "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

Sent when an extract operation encounters an error. 
{
  "success": false,
  "type": "extract.failed",
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "data": [],
  "error": "Failed to extract data: timeout exceeded",
  "metadata": {}
}

​
Event Filtering

You can control which events you receive by specifying an events array in your webhook configuration: 
{
  "url": "https://your-app.com/webhook",
  "events": ["completed", "failed"]
}