Overview

Real-time notifications for your Firecrawl operations

Get notified the moment a crawl, batch scrape, extract, or agent job 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

See Event Types for full payload details and examples.

Configuration

Tell Firecrawl where to deliver events by including a webhook object in your request. You can attach it to any supported operation, and the same object shape works across all of them.

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.