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

​
Supported Operations

OperationEvents
Crawlstarted, page, completed
Batch Scrapestarted, page, completed
Extractstarted, completed, failed
Agentstarted, 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"]
  }
}
FieldTypeRequiredDescription
urlstringYesYour endpoint URL (HTTPS)
headersobjectNoCustom headers to include
metadataobjectNoCustom data included in payloads
eventsarrayNoEvent 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:
RetryDelay after failure
1st1 minute
2nd5 minutes
3rd15 minutes
After 3 failed retries, the webhook is marked as failed and no further attempts are made.