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
Field | Type | Description |
---|
success | boolean | Whether the operation was successful |
type | string | Event type identifier |
id | string | Unique identifier for the job |
data | array | Event-specific data (varies by event type) |
metadata | object | Custom metadata from your webhook configuration |
error | string | Error 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": {}
}
LLM-powered data extraction operations.
Sent when an extract operation begins.
{
"success": true,
"type": "extract.started",
"id": "550e8400-e29b-41d4-a716-446655440000",
"data": [],
"metadata": {}
}
Sent when an extract operation finishes successfully.
{
"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": {}
}
Sent when an extract operation encounters an error.
{
"success": false,
"type": "extract.failed",
"id": "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"]
}