Webhooks

Get notified the moment a crawl, batch scrape, extract, agent job, or monitor check starts, progresses, or finishes. Instead of polling for status, you provide an HTTPS endpoint and Firecrawl delivers events to it in real time.

Supported Operations

Operation	Events
Crawl	`started`, `page`, `completed`
Batch Scrape	`started`, `page`, `completed`
Extract	`started`, `completed`, `failed`
Agent	`started`, `action`, `completed`, `failed`, `cancelled`
Monitor	`check.completed`

See Event Types for full payload details and examples.

Configuration

Add a webhook object to your request:

JSON

{
  "webhook": {
    "url": "https://your-domain.com/webhook",
    "metadata": {
      "any_key": "any_value"
    },
    "events": ["started", "page", "completed", "failed"]
  }
} 

Field	Type	Required	Description
`url`	string	Yes	Your endpoint URL (HTTPS)
`headers`	object	No	Custom headers to include
`metadata`	object	No	Custom data included in payloads
`events`	array	No	Event types to receive (default: all)

Usage

Crawl with Webhook

cURL

curl -X POST https://api.firecrawl.dev/v2/crawl \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -d '{
      "url": "https://docs.firecrawl.dev",
      "limit": 100,
      "webhook": {
        "url": "https://your-domain.com/webhook",
        "metadata": {
          "any_key": "any_value"
        },
        "events": ["started", "page", "completed"]
      }
    }'

Batch Scrape with Webhook

cURL

curl -X POST https://api.firecrawl.dev/v2/batch/scrape \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -d '{
      "urls": [
        "https://example.com/page1",
        "https://example.com/page2",
        "https://example.com/page3"
      ],
      "webhook": {
        "url": "https://your-domain.com/webhook",
        "metadata": {
          "any_key": "any_value"
        },
        "events": ["started", "page", "completed"]
      }
    }' 

Timeouts & Retries

Your endpoint must respond with a 2xx status within 10 seconds. If delivery fails (timeout, non-2xx, or network error), Firecrawl retries automatically:

Retry	Delay after failure
1st	1 minute
2nd	5 minutes
3rd	15 minutes

After 3 failed retries, the webhook is marked as failed and no further attempts are made.

Get Started

Core Endpoints

More

Quickstarts

Developer Guides

Use Cases

Other

Contributing

Overview

Supported Operations

Configuration

Usage

Crawl with Webhook

Batch Scrape with Webhook

Timeouts & Retries

​Supported Operations

​Configuration

​Usage

​Crawl with Webhook

​Batch Scrape with Webhook

​Timeouts & Retries

Supported Operations

Configuration

Usage

Crawl with Webhook

Batch Scrape with Webhook

Timeouts & Retries