> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firecrawl.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Tipos de eventos

> Referencia 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.

<div id="quick-reference">
  ## Referencia rápida
</div>

| 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 |

<div id="payload-structure">
  ## Estructura del payload
</div>

Todos los eventos de webhook comparten esta estructura:

```json theme={null}
{
  "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`)                 |

<div id="crawl-events">
  ## Eventos de rastreo
</div>

<div id="crawlstarted">
  ### `crawl.started`
</div>

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

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

<div id="crawlpage">
  ### `crawl.page`
</div>

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

```json theme={null}
{
  "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": {}
}
```

<div id="crawlcompleted">
  ### `crawl.completed`
</div>

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

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

<div id="batch-scrape-events">
  ## Eventos de scraping por lotes
</div>

<div id="batch_scrapestarted">
  ### `batch_scrape.started`
</div>

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

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

<div id="batch_scrapepage">
  ### `batch_scrape.page`
</div>

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

```json theme={null}
{
  "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": {}
}
```

<div id="batch_scrapecompleted">
  ### `batch_scrape.completed`
</div>

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

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

<div id="monitor-events">
  ## Eventos del Monitor
</div>

<div id="monitorpage">
  ### `monitor.page`
</div>

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.

```json monitor.page theme={null}
{
  "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"
  }
}
```

<div id="monitorcheckcompleted">
  ### `monitor.check.completed`
</div>

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.

```json monitor.check.completed theme={null}
{
  "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.

<div id="extract-events">
  ## Eventos de extracción
</div>

<div id="extractstarted">
  ### `extract.started`
</div>

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

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

<div id="extractcompleted">
  ### `extract.completed`
</div>

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.

```json theme={null}
{
  "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": {}
}
```

<div id="extractfailed">
  ### `extract.failed`
</div>

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

```json theme={null}
{
  "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": {}
}
```

<div id="agent-events">
  ## Eventos del agente
</div>

<div id="agentstarted">
  ### `agent.started`
</div>

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

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

<div id="agentaction">
  ### `agent.action`
</div>

Se envía tras cada ejecución de una herramienta (`scrape`, `search`, etc.).

```json theme={null}
{
  "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>
  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`.
</Note>

<div id="agentcompleted">
  ### `agent.completed`
</div>

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

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

<div id="agentfailed">
  ### `agent.failed`
</div>

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

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

<div id="agentcancelled">
  ### `agent.cancelled`
</div>

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

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

<div id="event-filtering">
  ## Filtrado de eventos
</div>

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:

```json theme={null}
{
  "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.