Tipos de eventos de webhook

Firecrawl envía eventos de webhook en cada etapa del ciclo de vida de un trabajo, para que puedas seguir el progreso, capturar resultados y gestionar fallos en tiempo real sin necesidad de hacer polling.

Referencia rápida

Evento	Activador
`crawl.started`	El trabajo de rastreo comienza a procesarse
`crawl.page`	Se extrae una página durante un rastreo
`crawl.completed`	El trabajo de rastreo finaliza y todas las páginas se han procesado
`batch_scrape.started`	El trabajo de extracción por lotes comienza a procesarse
`batch_scrape.page`	Se extrae una URL durante una extracción por lotes
`batch_scrape.completed`	Todas las URL del lote se han procesado
`extract.started`	El trabajo de extracción comienza a procesarse
`extract.completed`	La extracción finaliza correctamente
`extract.failed`	La extracción falla
`agent.started`	El trabajo de agente comienza a procesarse
`agent.action`	El agente ejecuta una herramienta (scrape, search, etc.)
`agent.completed`	El agente finaliza correctamente
`agent.failed`	El agente se encuentra con un error
`agent.cancelled`	El trabajo de agente es cancelado por el usuario
`monitor.page`	Finaliza la extracción de una página supervisada
`monitor.check.completed`	La comprobación del monitor finaliza y los cambios a nivel de página están disponibles

Estructura del payload

Todos los eventos de webhook comparten esta estructura:

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

Field	Type	Description
`success`	boolean	Indica si la operación se completó correctamente
`type`	string	Tipo de evento (por ejemplo, `crawl.page`)
`id`	string	ID del trabajo
`data`	array u object	Datos específicos del evento (consulta los ejemplos más abajo)
`metadata`	object	Metadatos personalizados de tu configuración de webhook
`error`	string	Mensaje de error (cuando `success` es `false`)

Eventos de rastreo

`crawl.started`

Se envía cuando la tarea de rastreo comienza a procesarse.

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

`crawl.page`

Se envía por cada página que se extrae. El arreglo data contiene el contenido de la página y sus metadatos.

{
  "success": true,
  "type": "crawl.page",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [
    {
      "markdown": "# Page content...",
      "metadata": {
        "title": "Page Title",
        "description": "Descripción de la 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`

Se envía cuando el trabajo de rastreo finaliza y todas las páginas han sido procesadas.

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

Eventos de scraping por lotes

`batch_scrape.started`

Se envía cuando comienza una operación de scraping por lotes.

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

`batch_scrape.page`

Se envía por cada URL individual que se extrae. El arreglo data contiene el contenido de la página y sus metadatos.

{
  "success": true,
  "type": "batch_scrape.page",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [
    {
      "markdown": "# Page content...",
      "metadata": {
        "title": "Page Title",
        "description": "Descripción de la 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`

Se envía cuando se han procesado todas las URL del lote.

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

Eventos del Monitor

`monitor.page`

Se envía cuando finaliza el scraping de cada página supervisada. Este evento se emite desde la ruta del worker de scraping, por lo que llega antes de que se haya conciliado la verificación completa del monitor.

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`

Se envía cuando finaliza una verificación del monitor. El objeto data contiene el estado de la verificación y los recuentos de resumen. Los resultados a nivel de página solo se envían mediante eventos monitor.page o los devuelve la API de verificación del 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 es true cuando la verificación se completa sin errores de página. En verificaciones parciales o fallidas, success es false y error puede contener un mensaje.

Eventos de extracción

`extract.started`

Se envía cuando el trabajo de extracción comienza a ejecutarse.

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

`extract.completed`

Se envía cuando una operación de extracción se completa correctamente. El array data contiene los datos extraídos y la información de uso.

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

`extract.failed`

Se envía cuando falla la extracción. El campo error contiene el motivo del error.

{
  "success": false,
  "type": "extract.failed",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [],
  "error": "No se pudieron extraer los datos: se superó el tiempo de espera",
  "metadata": {}
}

Eventos del agente

Se envían para los trabajos iniciados con un webhook en /v2/agent.

`agent.started`

Se envía cuando el trabajo del agente comienza su procesamiento.

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

`agent.action`

Se envía tras cada ejecución de una herramienta (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": {}
}

El valor de creditsUsed en los eventos de action es una estimación del total de créditos utilizados hasta ese momento. El recuento final y preciso de créditos solo está disponible en los eventos completed, failed o cancelled.

`agent.completed`

Se envía cuando el agente finaliza correctamente. El array data contiene los datos extraídos y el total de créditos utilizados.

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

Se envía cuando el agente se encuentra con un error. El campo error contiene el motivo del fallo.

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

`agent.cancelled`

Se envía cuando el usuario cancela la tarea del agente.

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

Filtrado de eventos

De forma predeterminada, recibes todos los eventos. Para suscribirte solo a eventos específicos, usa el array events en la configuración de tu webhook:

{
  "url": "https://your-app.com/webhook",
  "events": ["completed", "failed"]
}

Esto es útil si solo te interesa que el trabajo se complete y no necesitas actualizaciones por página.

Primeros pasos

Endpoints principales

Más

Inicios rápidos

Guías para desarrolladores

Webhooks

Casos de uso

Otros

Contribuciones

Tipos de eventos

Referencia rápida

Estructura del payload

Eventos de rastreo

`crawl.started`

`crawl.page`

`crawl.completed`

Eventos de scraping por lotes

`batch_scrape.started`

`batch_scrape.page`

`batch_scrape.completed`

Eventos del Monitor

`monitor.page`

`monitor.check.completed`

Eventos de extracción

`extract.started`

`extract.completed`

`extract.failed`

Eventos del agente

`agent.started`

`agent.action`

`agent.completed`

`agent.failed`

`agent.cancelled`

Filtrado de eventos

​Referencia rápida

​Estructura del payload

​Eventos de rastreo

​crawl.started

​crawl.page

​crawl.completed

​Eventos de scraping por lotes

​batch_scrape.started

​batch_scrape.page

​batch_scrape.completed

​Eventos del Monitor

​monitor.page

​monitor.check.completed

​Eventos de extracción

​extract.started

​extract.completed

​extract.failed

​Eventos del agente

​agent.started

​agent.action

​agent.completed

​agent.failed

​agent.cancelled

​Filtrado de eventos

Referencia rápida

Estructura del payload

Eventos de rastreo

`crawl.started`

`crawl.page`

`crawl.completed`

Eventos de scraping por lotes

`batch_scrape.started`

`batch_scrape.page`

`batch_scrape.completed`

Eventos del Monitor

`monitor.page`

`monitor.check.completed`

Eventos de extracción

`extract.started`

`extract.completed`

`extract.failed`

Eventos del agente

`agent.started`

`agent.action`

`agent.completed`

`agent.failed`

`agent.cancelled`

Filtrado de eventos