# Overview (/webhooks/overview)

<!-- agent-signals: reading_time_min: 2 · est_tokens: 788 · updated: 2026-07-30 -->
Related: [Event Types](/webhooks/events.md), [Security](/webhooks/security.md), [Testing](/webhooks/testing.md), [Firecrawl + Dify](/developer-guides/workflow-automation/dify.md)

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

## Configuration [#configuration]

Add a `webhook` object to your request:

```json title="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 [#usage]

### Crawl with Webhook [#crawl-with-webhook]

```bash title="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 [#batch-scrape-with-webhook]

```bash title="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 [#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.