Tipos de eventos de webhook

O Firecrawl envia eventos de webhook em cada etapa do ciclo de vida de um job, para que você possa acompanhar o progresso, capturar resultados e lidar com falhas em tempo real sem precisar fazer consultas.

Referência rápida

Evento	Gatilho
`crawl.started`	O job de rastreamento começa a ser processado
`crawl.page`	Uma página é extraída durante um rastreamento
`crawl.completed`	O job de rastreamento é concluído e todas as páginas foram processadas
`batch_scrape.started`	O job de extração em lote começa a ser processado
`batch_scrape.page`	Uma URL é extraída durante uma extração em lote
`batch_scrape.completed`	Todas as URLs do lote foram processadas
`extract.started`	O job de extração começa a ser processado
`extract.completed`	A extração é concluída com sucesso
`extract.failed`	A extração falha
`agent.started`	O job do agente começa a ser processado
`agent.action`	O agente executa uma ferramenta (scraping, busca etc.)
`agent.completed`	O agente é concluído com sucesso
`agent.failed`	O agente encontra um erro
`agent.cancelled`	O job do agente é cancelado pelo usuário
`monitor.page`	O scraping de uma página monitorada é concluído
`monitor.check.completed`	A verificação do monitor é concluída e as mudanças no nível da página ficam disponíveis

Estrutura do payload

Todos os eventos de webhook compartilham esta estrutura:

{
  "success": true,
  "type": "crawl.page",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [...],
  "metadata": {}
}

Field	Type	Description
`success`	boolean	Se a operação foi bem-sucedida
`type`	string	Tipo de evento (por exemplo, `crawl.page`)
`id`	string	ID do job
`data`	array or object	Dados específicos do evento (veja exemplos abaixo)
`metadata`	object	Metadados personalizados da sua configuração de webhook
`error`	string	Mensagem de erro (quando `success` é `false`)

Eventos de Crawl

`crawl.started`

Enviado quando a operação de rastreamento começa a ser processada.

{
  "success": true,
  "type": "crawl.started",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [],
  "metadata": {}
}

`crawl.page`

Enviado para cada página extraída. O array data contém o conteúdo da página e seus metadados.

{
  "success": true,
  "type": "crawl.page",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [
    {
      "markdown": "# Page content...",
      "metadata": {
        "title": "Título da página",
        "description": "Descrição da página",
        "url": "https://example.com/page",
        "statusCode": 200,
        "contentType": "text/html",
        "scrapeId": "550e8400-e29b-41d4-a716-446655440001",
        "sourceURL": "https://example.com/page",
        "proxyUsed": "basic",
        "cacheState": "hit",
        "cachedAt": "2025-09-03T21:11:25.636Z",
        "creditsUsed": 1
      }
    }
  ],
  "metadata": {}
}

`crawl.completed`

Enviado quando toda a operação de rastreamento é concluída e todas as páginas foram processadas.

{
  "success": true,
  "type": "crawl.completed",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [],
  "metadata": {}
}

Eventos de Scrape em Lote

`batch_scrape.started`

Enviado quando a tarefa de raspagem em lote começa a ser processada.

{
  "success": true,
  "type": "batch_scrape.started",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [],
  "metadata": {}
}

`batch_scrape.page`

Enviado para cada URL processada na raspagem. O array data contém o conteúdo da página e seus metadados.

{
  "success": true,
  "type": "batch_scrape.page",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [
    {
      "markdown": "# Page content...",
      "metadata": {
        "title": "Page Title",
        "description": "Descrição da página",
        "url": "https://example.com",
        "statusCode": 200,
        "contentType": "text/html",
        "scrapeId": "550e8400-e29b-41d4-a716-446655440001",
        "sourceURL": "https://example.com",
        "proxyUsed": "basic",
        "cacheState": "miss",
        "cachedAt": "2025-09-03T23:30:53.434Z",
        "creditsUsed": 1
      }
    }
  ],
  "metadata": {}
}

`batch_scrape.completed`

Enviado quando todas as URLs do lote tiverem sido processadas.

{
  "success": true,
  "type": "batch_scrape.completed",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [],
  "metadata": {}
}

Eventos do Monitor

`monitor.page`

Enviado quando o scraping de cada página monitorada é concluído. Esse evento é emitido pela rota do worker de scraping, portanto chega antes que a verificação completa do monitor seja consolidada.

monitor.page

{
  "success": true,
  "type": "monitor.page",
  "id": "019df960-5f2a-75fb-a98b-bd2d32ca67d4",
  "webhookId": "f1e2d3c4-0000-0000-0000-000000000000",
  "data": [
    {
      "monitorId": "019df960-06e7-7383-9d89-82c0113dc31a",
      "checkId": "019df960-5f2a-75fb-a98b-bd2d32ca67d4",
      "url": "https://example.com/blog",
      "status": "changed",
      "previousScrapeId": "019df94f-82c3-7e41-81f0-00c72b2d9c52",
      "currentScrapeId": "019df960-73ee-7ac2-97a9-fb0e442c21f1",
      "error": null,
      "isMeaningful": true,
      "judgment": {
        "meaningful": true,
        "confidence": "high",
        "reason": "The page headline changed to announce a new release cadence.",
        "meaningfulChanges": [
          {
            "type": "changed",
            "before": "Welcome to our weekly update.",
            "after": "Welcome to our weekly update — now with daily releases!",
            "reason": "The headline changed in a way that matches the monitor goal."
          }
        ]
      },
      "diff": {
        "text": "--- previous\n+++ current\n@@ -1,3 +1,3 @@\n # Latest posts\n-Welcome to our weekly update.\n+Welcome to our weekly update — now with daily releases!\n"
      }
    }
  ],
  "metadata": {
    "environment": "production"
  }
}

`monitor.check.completed`

Enviado quando uma verificação do monitor é concluída. O objeto data contém o status da verificação e contagens resumidas. Os resultados por página são enviados apenas por meio de eventos monitor.page ou retornados pela API de verificação do monitor.

monitor.check.completed

{
  "success": true,
  "type": "monitor.check.completed",
  "id": "019df960-5f2a-75fb-a98b-bd2d32ca67d4",
  "webhookId": "f1e2d3c4-0001-0000-0000-000000000000",
  "data": [
    {
      "monitorId": "019df960-06e7-7383-9d89-82c0113dc31a",
      "checkId": "019df960-5f2a-75fb-a98b-bd2d32ca67d4",
      "status": "completed",
      "summary": {
        "totalPages": 2,
        "same": 1,
        "changed": 1,
        "new": 0,
        "removed": 0,
        "error": 0
      }
    }
  ],
  "metadata": {
    "environment": "production"
  }
}

success é true quando a verificação é concluída sem erros de página. Em verificações parciais ou com falha, success é false e error pode conter uma mensagem.

Eventos de Extração

`extract.started`

Enviado quando a tarefa de extração começa a ser processada.

{
  "success": true,
  "type": "extract.started",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [],
  "metadata": {}
}

`extract.completed`

Enviado quando uma operação de extração é concluída com sucesso. O array data contém os dados extraídos e as informações de uso.

{
  "success": true,
  "type": "extract.completed",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [
    {
      "success": true,
      "data": { "siteName": "Exemplo Site", "category": "Tecnologia" },
      "extractId": "550e8400-e29b-41d4-a716-446655440000",
      "llmUsage": 0.0020118,
      "totalUrlsScraped": 1,
      "sources": {
        "siteName": ["https://example.com"],
        "category": ["https://example.com"]
      }
    }
  ],
  "metadata": {}
}

`extract.failed`

Enviado quando a extração falha. O campo error contém o motivo do erro.

{
  "success": false,
  "type": "extract.failed",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [],
  "error": "Falha na extração de dados: tempo limite excedido",
  "metadata": {}
}

Eventos de agente

`agent.started`

Enviado quando a tarefa do agente começa a ser processada.

{
  "success": true,
  "type": "agent.started",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [],
  "metadata": {}
}

`agent.action`

Enviado após cada execução de uma ferramenta (scrape, search, etc.).

{
  "success": true,
  "type": "agent.action",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [
    {
      "creditsUsed": 5,
      "action": "mcp__tools__scrape",
      "input": {
        "url": "https://example.com"
      }
    }
  ],
  "metadata": {}
}

O valor de creditsUsed em eventos de action é uma estimativa do total de créditos usados até o momento. A contagem exata de créditos só está disponível nos eventos completed, failed ou cancelled.

`agent.completed`

Enviado quando o agente conclui a execução com sucesso. O array data contém os dados extraídos e o total de créditos consumidos.

{
  "success": true,
  "type": "agent.completed",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [
    {
      "creditsUsed": 15,
      "data": {
        "company": "Example Corp",
        "industry": "Technology",
        "founded": 2020
      }
    }
  ],
  "metadata": {}
}

`agent.failed`

Enviado quando o agente encontra um erro. O campo error contém o motivo da falha.

{
  "success": false,
  "type": "agent.failed",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [
    {
      "creditsUsed": 8
    }
  ],
  "error": "Créditos máximos excedidos",
  "metadata": {}
}

`agent.cancelled`

Enviado quando a tarefa do agente é cancelada pelo usuário.

{
  "success": false,
  "type": "agent.cancelled",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [
    {
      "creditsUsed": 3
    }
  ],
  "metadata": {}
}

Filtragem de eventos

Por padrão, você recebe todos os eventos. Para receber apenas eventos específicos, use o array events na configuração do seu webhook:

{
  "url": "https://your-app.com/webhook",
  "events": ["concluído", "falhou"]
}

Isso é útil se você se importa apenas com a conclusão da tarefa e não precisa de atualizações por página.

​Referência rápida

​Estrutura do payload

​Eventos de Crawl

​crawl.started

​crawl.page

​crawl.completed

​Eventos de Scrape em Lote

​batch_scrape.started

​batch_scrape.page

​batch_scrape.completed

​Eventos do Monitor

​monitor.page

​monitor.check.completed

​Eventos de Extração

​extract.started

​extract.completed

​extract.failed

​Eventos de agente

​agent.started

​agent.action

​agent.completed

​agent.failed

​agent.cancelled

​Filtragem de eventos

Referência rápida

Estrutura do payload

Eventos de Crawl

`crawl.started`

`crawl.page`

`crawl.completed`

Eventos de Scrape em Lote

`batch_scrape.started`

`batch_scrape.page`

`batch_scrape.completed`

Eventos do Monitor

`monitor.page`

`monitor.check.completed`

Eventos de Extração

`extract.started`

`extract.completed`

`extract.failed`

Eventos de agente

`agent.started`

`agent.action`

`agent.completed`

`agent.failed`

`agent.cancelled`

Filtragem de eventos