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

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.

Primeiros passos

Endpoints principais

Mais

Guias de início rápido

Guias para desenvolvedores

Webhooks

Casos de uso

Outros

Como contribuir

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

`agent.started`

`agent.action`

`agent.completed`

`agent.failed`

`agent.cancelled`

Filtragem de eventos