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

# Webhooks

> Firecrawl incoming webhooks: event paths, payloads, and response data.

The Firecrawl plugin handles incoming webhooks. Point your provider’s subscription URL at your Corsair HTTP handler (see [Overview](/plugins/firecrawl/overview) for setup context and the exact URL shape).

<Info>
  **New to Corsair?** See [webhooks](/concepts/webhooks) and [hooks](/concepts/hooks).
</Info>

## Webhook map

* `agent`
  * `action` (`agent.action`)
  * `cancelled` (`agent.cancelled`)
  * `completed` (`agent.completed`)
  * `failed` (`agent.failed`)
  * `started` (`agent.started`)
* `batchScrape`
  * `completed` (`batchScrape.completed`)
  * `page` (`batchScrape.page`)
  * `started` (`batchScrape.started`)
* `crawl`
  * `completed` (`crawl.completed`)
  * `page` (`crawl.page`)
  * `started` (`crawl.started`)
* `extract`
  * `completed` (`extract.completed`)
  * `failed` (`extract.failed`)
  * `started` (`extract.started`)

## HTTP handler setup

```ts app/api/webhook/route.ts theme={null}
import { processWebhook } from "corsair";
import { corsair } from "@/server/corsair";

export async function POST(request: Request) {
    const headers = Object.fromEntries(request.headers);
    const body = await request.json();
    const result = await processWebhook(corsair, headers, body);
    return result.response;
}
```

## Events

## Agent

### Action

`agent.action`

The agent executed a tool action

**Payload**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `boolean` | Yes | — |
| `type` | `agent.action` | Yes | — |
| `id` | `string` | Yes | — |
| `data` | `object[]` | Yes | — |
| `metadata` | `object` | No | — |
| `error` | `string` | No | — |

<AccordionGroup>
  <Accordion title="data full type">
    ```ts theme={null}
    {
      creditsUsed?: number,
      action?: string,
      input?: {
      }
    }[]
    ```
  </Accordion>

  <Accordion title="metadata full type">
    ```ts theme={null}
    {
    }
    ```
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Response data full type">
    ```ts theme={null}
    {
      success: boolean,
      type: agent.action,
      id: string,
      data: {
        creditsUsed?: number,
        action?: string,
        input?: {
        }
      }[],
      metadata?: {
      },
      error?: string
    }
    ```
  </Accordion>
</AccordionGroup>

**`webhookHooks` example**

```ts theme={null}
firecrawl({
    webhookHooks: {
        agent: {
            action: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})
```

***

### Cancelled

`agent.cancelled`

An agent job was cancelled

**Payload**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `boolean` | Yes | — |
| `type` | `agent.cancelled` | Yes | — |
| `id` | `string` | Yes | — |
| `data` | `object[]` | Yes | — |
| `metadata` | `object` | No | — |
| `error` | `string` | No | — |

<AccordionGroup>
  <Accordion title="data full type">
    ```ts theme={null}
    {
      creditsUsed?: number
    }[]
    ```
  </Accordion>

  <Accordion title="metadata full type">
    ```ts theme={null}
    {
    }
    ```
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Response data full type">
    ```ts theme={null}
    {
      success: boolean,
      type: agent.cancelled,
      id: string,
      data: {
        creditsUsed?: number
      }[],
      metadata?: {
      },
      error?: string
    }
    ```
  </Accordion>
</AccordionGroup>

**`webhookHooks` example**

```ts theme={null}
firecrawl({
    webhookHooks: {
        agent: {
            cancelled: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})
```

***

### Completed

`agent.completed`

An agent job completed successfully

**Payload**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `boolean` | Yes | — |
| `type` | `agent.completed` | Yes | — |
| `id` | `string` | Yes | — |
| `data` | `object[]` | Yes | — |
| `metadata` | `object` | No | — |
| `error` | `string` | No | — |

<AccordionGroup>
  <Accordion title="data full type">
    ```ts theme={null}
    {
      creditsUsed?: number,
      data?: {
      }
    }[]
    ```
  </Accordion>

  <Accordion title="metadata full type">
    ```ts theme={null}
    {
    }
    ```
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Response data full type">
    ```ts theme={null}
    {
      success: boolean,
      type: agent.completed,
      id: string,
      data: {
        creditsUsed?: number,
        data?: {
        }
      }[],
      metadata?: {
      },
      error?: string
    }
    ```
  </Accordion>
</AccordionGroup>

**`webhookHooks` example**

```ts theme={null}
firecrawl({
    webhookHooks: {
        agent: {
            completed: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})
```

***

### Failed

`agent.failed`

An agent job failed

**Payload**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `boolean` | Yes | — |
| `type` | `agent.failed` | Yes | — |
| `id` | `string` | Yes | — |
| `data` | `object[]` | Yes | — |
| `metadata` | `object` | No | — |
| `error` | `string` | No | — |

<AccordionGroup>
  <Accordion title="data full type">
    ```ts theme={null}
    {
      creditsUsed?: number
    }[]
    ```
  </Accordion>

  <Accordion title="metadata full type">
    ```ts theme={null}
    {
    }
    ```
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Response data full type">
    ```ts theme={null}
    {
      success: boolean,
      type: agent.failed,
      id: string,
      data: {
        creditsUsed?: number
      }[],
      metadata?: {
      },
      error?: string
    }
    ```
  </Accordion>
</AccordionGroup>

**`webhookHooks` example**

```ts theme={null}
firecrawl({
    webhookHooks: {
        agent: {
            failed: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})
```

***

### Started

`agent.started`

An agent job started

**Payload**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `boolean` | Yes | — |
| `type` | `agent.started` | Yes | — |
| `id` | `string` | Yes | — |
| `data` | `never[]` | Yes | — |
| `metadata` | `object` | No | — |
| `error` | `string` | No | — |

<AccordionGroup>
  <Accordion title="metadata full type">
    ```ts theme={null}
    {
    }
    ```
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Response data full type">
    ```ts theme={null}
    {
      success: boolean,
      type: agent.started,
      id: string,
      data: never[],
      metadata?: {
      },
      error?: string
    }
    ```
  </Accordion>
</AccordionGroup>

**`webhookHooks` example**

```ts theme={null}
firecrawl({
    webhookHooks: {
        agent: {
            started: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})
```

***

## Batch Scrape

### Completed

`batchScrape.completed`

A batch scrape job completed

**Payload**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `boolean` | Yes | — |
| `type` | `batch_scrape.completed` | Yes | — |
| `id` | `string` | Yes | — |
| `data` | `never[]` | Yes | — |
| `metadata` | `object` | No | — |
| `error` | `string` | No | — |

<AccordionGroup>
  <Accordion title="metadata full type">
    ```ts theme={null}
    {
    }
    ```
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Response data full type">
    ```ts theme={null}
    {
      success: boolean,
      type: batch_scrape.completed,
      id: string,
      data: never[],
      metadata?: {
      },
      error?: string
    }
    ```
  </Accordion>
</AccordionGroup>

**`webhookHooks` example**

```ts theme={null}
firecrawl({
    webhookHooks: {
        batchScrape: {
            completed: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})
```

***

### Page

`batchScrape.page`

A URL was scraped in a batch job

**Payload**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `boolean` | Yes | — |
| `type` | `batch_scrape.page` | Yes | — |
| `id` | `string` | Yes | — |
| `data` | `object[]` | Yes | — |
| `metadata` | `object` | No | — |
| `error` | `string` | No | — |

<AccordionGroup>
  <Accordion title="data full type">
    ```ts theme={null}
    {
      markdown?: string,
      html?: string | null,
      rawHtml?: string | null,
      links?: string[],
      screenshot?: string | null,
      metadata?: {
        title?: string | string[],
        description?: string | string[],
        language?: string | string[] | null,
        keywords?: string | string[],
        sourceURL?: string,
        url?: string,
        scrapeId?: string,
        statusCode?: number,
        contentType?: string,
        error?: string | null,
        ogLocaleAlternate?: string[],
        concurrencyLimited?: boolean,
        concurrencyQueueDurationMs?: number
      }
    }[]
    ```
  </Accordion>

  <Accordion title="metadata full type">
    ```ts theme={null}
    {
    }
    ```
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Response data full type">
    ```ts theme={null}
    {
      success: boolean,
      type: batch_scrape.page,
      id: string,
      data: {
        markdown?: string,
        html?: string | null,
        rawHtml?: string | null,
        links?: string[],
        screenshot?: string | null,
        metadata?: {
          title?: string | string[],
          description?: string | string[],
          language?: string | string[] | null,
          keywords?: string | string[],
          sourceURL?: string,
          url?: string,
          scrapeId?: string,
          statusCode?: number,
          contentType?: string,
          error?: string | null,
          ogLocaleAlternate?: string[],
          concurrencyLimited?: boolean,
          concurrencyQueueDurationMs?: number
        }
      }[],
      metadata?: {
      },
      error?: string
    }
    ```
  </Accordion>
</AccordionGroup>

**`webhookHooks` example**

```ts theme={null}
firecrawl({
    webhookHooks: {
        batchScrape: {
            page: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})
```

***

### Started

`batchScrape.started`

A batch scrape job started

**Payload**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `boolean` | Yes | — |
| `type` | `batch_scrape.started` | Yes | — |
| `id` | `string` | Yes | — |
| `data` | `never[]` | Yes | — |
| `metadata` | `object` | No | — |
| `error` | `string` | No | — |

<AccordionGroup>
  <Accordion title="metadata full type">
    ```ts theme={null}
    {
    }
    ```
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Response data full type">
    ```ts theme={null}
    {
      success: boolean,
      type: batch_scrape.started,
      id: string,
      data: never[],
      metadata?: {
      },
      error?: string
    }
    ```
  </Accordion>
</AccordionGroup>

**`webhookHooks` example**

```ts theme={null}
firecrawl({
    webhookHooks: {
        batchScrape: {
            started: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})
```

***

## Crawl

### Completed

`crawl.completed`

A crawl job finished

**Payload**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `boolean` | Yes | — |
| `type` | `crawl.completed` | Yes | — |
| `id` | `string` | Yes | — |
| `data` | `never[]` | Yes | — |
| `metadata` | `object` | No | — |
| `error` | `string` | No | — |

<AccordionGroup>
  <Accordion title="metadata full type">
    ```ts theme={null}
    {
    }
    ```
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Response data full type">
    ```ts theme={null}
    {
      success: boolean,
      type: crawl.completed,
      id: string,
      data: never[],
      metadata?: {
      },
      error?: string
    }
    ```
  </Accordion>
</AccordionGroup>

**`webhookHooks` example**

```ts theme={null}
firecrawl({
    webhookHooks: {
        crawl: {
            completed: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})
```

***

### Page

`crawl.page`

A page was scraped during a crawl

**Payload**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `boolean` | Yes | — |
| `type` | `crawl.page` | Yes | — |
| `id` | `string` | Yes | — |
| `data` | `object[]` | Yes | — |
| `metadata` | `object` | No | — |
| `error` | `string` | No | — |

<AccordionGroup>
  <Accordion title="data full type">
    ```ts theme={null}
    {
      markdown?: string,
      html?: string | null,
      rawHtml?: string | null,
      links?: string[],
      screenshot?: string | null,
      metadata?: {
        title?: string | string[],
        description?: string | string[],
        language?: string | string[] | null,
        keywords?: string | string[],
        sourceURL?: string,
        url?: string,
        scrapeId?: string,
        statusCode?: number,
        contentType?: string,
        error?: string | null,
        ogLocaleAlternate?: string[],
        concurrencyLimited?: boolean,
        concurrencyQueueDurationMs?: number
      }
    }[]
    ```
  </Accordion>

  <Accordion title="metadata full type">
    ```ts theme={null}
    {
    }
    ```
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Response data full type">
    ```ts theme={null}
    {
      success: boolean,
      type: crawl.page,
      id: string,
      data: {
        markdown?: string,
        html?: string | null,
        rawHtml?: string | null,
        links?: string[],
        screenshot?: string | null,
        metadata?: {
          title?: string | string[],
          description?: string | string[],
          language?: string | string[] | null,
          keywords?: string | string[],
          sourceURL?: string,
          url?: string,
          scrapeId?: string,
          statusCode?: number,
          contentType?: string,
          error?: string | null,
          ogLocaleAlternate?: string[],
          concurrencyLimited?: boolean,
          concurrencyQueueDurationMs?: number
        }
      }[],
      metadata?: {
      },
      error?: string
    }
    ```
  </Accordion>
</AccordionGroup>

**`webhookHooks` example**

```ts theme={null}
firecrawl({
    webhookHooks: {
        crawl: {
            page: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})
```

***

### Started

`crawl.started`

A crawl job started processing

**Payload**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `boolean` | Yes | — |
| `type` | `crawl.started` | Yes | — |
| `id` | `string` | Yes | — |
| `data` | `never[]` | Yes | — |
| `metadata` | `object` | No | — |
| `error` | `string` | No | — |

<AccordionGroup>
  <Accordion title="metadata full type">
    ```ts theme={null}
    {
    }
    ```
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Response data full type">
    ```ts theme={null}
    {
      success: boolean,
      type: crawl.started,
      id: string,
      data: never[],
      metadata?: {
      },
      error?: string
    }
    ```
  </Accordion>
</AccordionGroup>

**`webhookHooks` example**

```ts theme={null}
firecrawl({
    webhookHooks: {
        crawl: {
            started: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})
```

***

## Extract

### Completed

`extract.completed`

An extract job completed successfully

**Payload**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `boolean` | Yes | — |
| `type` | `extract.completed` | Yes | — |
| `id` | `string` | Yes | — |
| `data` | `object[]` | Yes | — |
| `metadata` | `object` | No | — |
| `error` | `string` | No | — |

<AccordionGroup>
  <Accordion title="data full type">
    ```ts theme={null}
    {
      success: boolean,
      data: {
      },
      extractId: string,
      llmUsage?: number,
      totalUrlsScraped?: number,
      sources?: {
      }
    }[]
    ```
  </Accordion>

  <Accordion title="metadata full type">
    ```ts theme={null}
    {
    }
    ```
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Response data full type">
    ```ts theme={null}
    {
      success: boolean,
      type: extract.completed,
      id: string,
      data: {
        success: boolean,
        data: {
        },
        extractId: string,
        llmUsage?: number,
        totalUrlsScraped?: number,
        sources?: {
        }
      }[],
      metadata?: {
      },
      error?: string
    }
    ```
  </Accordion>
</AccordionGroup>

**`webhookHooks` example**

```ts theme={null}
firecrawl({
    webhookHooks: {
        extract: {
            completed: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})
```

***

### Failed

`extract.failed`

An extract job failed

**Payload**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `boolean` | Yes | — |
| `type` | `extract.failed` | Yes | — |
| `id` | `string` | Yes | — |
| `data` | `never[]` | Yes | — |
| `metadata` | `object` | No | — |
| `error` | `string` | No | — |

<AccordionGroup>
  <Accordion title="metadata full type">
    ```ts theme={null}
    {
    }
    ```
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Response data full type">
    ```ts theme={null}
    {
      success: boolean,
      type: extract.failed,
      id: string,
      data: never[],
      metadata?: {
      },
      error?: string
    }
    ```
  </Accordion>
</AccordionGroup>

**`webhookHooks` example**

```ts theme={null}
firecrawl({
    webhookHooks: {
        extract: {
            failed: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})
```

***

### Started

`extract.started`

An extract job started

**Payload**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `boolean` | Yes | — |
| `type` | `extract.started` | Yes | — |
| `id` | `string` | Yes | — |
| `data` | `never[]` | Yes | — |
| `metadata` | `object` | No | — |
| `error` | `string` | No | — |

<AccordionGroup>
  <Accordion title="metadata full type">
    ```ts theme={null}
    {
    }
    ```
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Response data full type">
    ```ts theme={null}
    {
      success: boolean,
      type: extract.started,
      id: string,
      data: never[],
      metadata?: {
      },
      error?: string
    }
    ```
  </Accordion>
</AccordionGroup>

**`webhookHooks` example**

```ts theme={null}
firecrawl({
    webhookHooks: {
        extract: {
            started: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})
```

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.