Overview

Real-time notifications for your Firecrawl operations

Webhooks let you receive real-time notifications as your operations progress, instead of polling for status.

Supported Operations

Operation	Events
Crawl	started, page, completed
Batch Scrape	started, page, completed
Extract	started, completed, failed
Agent	started, action, completed, failed, cancelled

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.