> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firecrawl.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/webhooks/events) for full payload details and examples.

## Configuration

Add a `webhook` object to your request:

```json JSON theme={null}
{
  "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

```bash cURL theme={null}
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

```bash cURL theme={null}
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.