Skip to main content
The Firecrawl plugin handles incoming webhooks. Point your provider’s subscription URL at your Corsair HTTP handler (see Overview for setup context and the exact URL shape).
New to Corsair? See webhooks and hooks.

​
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

app/api/webhook/route.ts
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
NameTypeRequiredDescription
successbooleanYes—
typeagent.actionYes—
idstringYes—
dataobject[]Yes—
metadataobjectNo—
errorstringNo—
{
  creditsUsed?: number,
  action?: string,
  input?: {
  }
}[]

{
}

{
  success: boolean,
  type: agent.action,
  id: string,
  data: {
    creditsUsed?: number,
    action?: string,
    input?: {
    }
  }[],
  metadata?: {
  },
  error?: string
}
webhookHooks example 
firecrawl({
    webhookHooks: {
        agent: {
            action: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})

​
Cancelled

agent.cancelled An agent job was cancelled Payload
NameTypeRequiredDescription
successbooleanYes—
typeagent.cancelledYes—
idstringYes—
dataobject[]Yes—
metadataobjectNo—
errorstringNo—
{
  creditsUsed?: number
}[]

{
}

{
  success: boolean,
  type: agent.cancelled,
  id: string,
  data: {
    creditsUsed?: number
  }[],
  metadata?: {
  },
  error?: string
}
webhookHooks example 
firecrawl({
    webhookHooks: {
        agent: {
            cancelled: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})

​
Completed

agent.completed An agent job completed successfully Payload
NameTypeRequiredDescription
successbooleanYes—
typeagent.completedYes—
idstringYes—
dataobject[]Yes—
metadataobjectNo—
errorstringNo—
{
  creditsUsed?: number,
  data?: {
  }
}[]

{
}

{
  success: boolean,
  type: agent.completed,
  id: string,
  data: {
    creditsUsed?: number,
    data?: {
    }
  }[],
  metadata?: {
  },
  error?: string
}
webhookHooks example 
firecrawl({
    webhookHooks: {
        agent: {
            completed: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})

​
Failed

agent.failed An agent job failed Payload
NameTypeRequiredDescription
successbooleanYes—
typeagent.failedYes—
idstringYes—
dataobject[]Yes—
metadataobjectNo—
errorstringNo—
{
  creditsUsed?: number
}[]

{
}

{
  success: boolean,
  type: agent.failed,
  id: string,
  data: {
    creditsUsed?: number
  }[],
  metadata?: {
  },
  error?: string
}
webhookHooks example 
firecrawl({
    webhookHooks: {
        agent: {
            failed: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})

​
Started

agent.started An agent job started Payload
NameTypeRequiredDescription
successbooleanYes—
typeagent.startedYes—
idstringYes—
datanever[]Yes—
metadataobjectNo—
errorstringNo—
{
}

{
  success: boolean,
  type: agent.started,
  id: string,
  data: never[],
  metadata?: {
  },
  error?: string
}
webhookHooks example 
firecrawl({
    webhookHooks: {
        agent: {
            started: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})

​
Batch Scrape

​
Completed

batchScrape.completed A batch scrape job completed Payload
NameTypeRequiredDescription
successbooleanYes—
typebatch_scrape.completedYes—
idstringYes—
datanever[]Yes—
metadataobjectNo—
errorstringNo—
{
}

{
  success: boolean,
  type: batch_scrape.completed,
  id: string,
  data: never[],
  metadata?: {
  },
  error?: string
}
webhookHooks example 
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
NameTypeRequiredDescription
successbooleanYes—
typebatch_scrape.pageYes—
idstringYes—
dataobject[]Yes—
metadataobjectNo—
errorstringNo—
{
  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
  }
}[]

{
}

{
  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
}
webhookHooks example 
firecrawl({
    webhookHooks: {
        batchScrape: {
            page: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})

​
Started

batchScrape.started A batch scrape job started Payload
NameTypeRequiredDescription
successbooleanYes—
typebatch_scrape.startedYes—
idstringYes—
datanever[]Yes—
metadataobjectNo—
errorstringNo—
{
}

{
  success: boolean,
  type: batch_scrape.started,
  id: string,
  data: never[],
  metadata?: {
  },
  error?: string
}
webhookHooks example 
firecrawl({
    webhookHooks: {
        batchScrape: {
            started: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})

​
Crawl

​
Completed

crawl.completed A crawl job finished Payload
NameTypeRequiredDescription
successbooleanYes—
typecrawl.completedYes—
idstringYes—
datanever[]Yes—
metadataobjectNo—
errorstringNo—
{
}

{
  success: boolean,
  type: crawl.completed,
  id: string,
  data: never[],
  metadata?: {
  },
  error?: string
}
webhookHooks example 
firecrawl({
    webhookHooks: {
        crawl: {
            completed: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})

​
Page

crawl.page A page was scraped during a crawl Payload
NameTypeRequiredDescription
successbooleanYes—
typecrawl.pageYes—
idstringYes—
dataobject[]Yes—
metadataobjectNo—
errorstringNo—
{
  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
  }
}[]

{
}

{
  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
}
webhookHooks example 
firecrawl({
    webhookHooks: {
        crawl: {
            page: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})

​
Started

crawl.started A crawl job started processing Payload
NameTypeRequiredDescription
successbooleanYes—
typecrawl.startedYes—
idstringYes—
datanever[]Yes—
metadataobjectNo—
errorstringNo—
{
}

{
  success: boolean,
  type: crawl.started,
  id: string,
  data: never[],
  metadata?: {
  },
  error?: string
}
webhookHooks example 
firecrawl({
    webhookHooks: {
        crawl: {
            started: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})

​
Extract

​
Completed

extract.completed An extract job completed successfully Payload
NameTypeRequiredDescription
successbooleanYes—
typeextract.completedYes—
idstringYes—
dataobject[]Yes—
metadataobjectNo—
errorstringNo—
{
  success: boolean,
  data: {
  },
  extractId: string,
  llmUsage?: number,
  totalUrlsScraped?: number,
  sources?: {
  }
}[]

{
}

{
  success: boolean,
  type: extract.completed,
  id: string,
  data: {
    success: boolean,
    data: {
    },
    extractId: string,
    llmUsage?: number,
    totalUrlsScraped?: number,
    sources?: {
    }
  }[],
  metadata?: {
  },
  error?: string
}
webhookHooks example 
firecrawl({
    webhookHooks: {
        extract: {
            completed: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})

​
Failed

extract.failed An extract job failed Payload
NameTypeRequiredDescription
successbooleanYes—
typeextract.failedYes—
idstringYes—
datanever[]Yes—
metadataobjectNo—
errorstringNo—
{
}

{
  success: boolean,
  type: extract.failed,
  id: string,
  data: never[],
  metadata?: {
  },
  error?: string
}
webhookHooks example 
firecrawl({
    webhookHooks: {
        extract: {
            failed: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})

​
Started

extract.started An extract job started Payload
NameTypeRequiredDescription
successbooleanYes—
typeextract.startedYes—
idstringYes—
datanever[]Yes—
metadataobjectNo—
errorstringNo—
{
}

{
  success: boolean,
  type: extract.started,
  id: string,
  data: never[],
  metadata?: {
  },
  error?: string
}
webhookHooks example 
firecrawl({
    webhookHooks: {
        extract: {
            started: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})