Tipos de eventos - Firecrawl Docs

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 do agente#

Enviado para jobs iniciados com um webhook em /v2/agent.

`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": {}}

Note

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 do agente#

agent.started#

agent.action#

agent.completed#

agent.failed#

agent.cancelled#

Filtragem de eventos#

`crawl.started`#

`crawl.page`#

`crawl.completed`#

`batch_scrape.started`#

`batch_scrape.page`#

`batch_scrape.completed`#

`monitor.page`#

`monitor.check.completed`#

`extract.started`#

`extract.completed`#

`extract.failed`#

`agent.started`#

`agent.action`#

`agent.completed`#

`agent.failed`#

`agent.cancelled`#