> ## Documentation Index
> Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-ul56gh.mintlify.site/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.

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

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

<h2 id="payload-structure">
  Estructura del payload
</h2>

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

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

<h3 id="crawlstarted">
  `crawl.started`
</h3>

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

<h3 id="crawlpage">
  `crawl.page`
</h3>

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

<h3 id="crawlcompleted">
  `crawl.completed`
</h3>

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

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

<h3 id="batch_scrapestarted">
  `batch_scrape.started`
</h3>

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

<h3 id="batch_scrapepage">
  `batch_scrape.page`
</h3>

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

<h3 id="batch_scrapecompleted">
  `batch_scrape.completed`
</h3>

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

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

<h3 id="monitorpage">
  `monitor.page`
</h3>

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

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

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.

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

<h3 id="extractstarted">
  `extract.started`
</h3>

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

<h3 id="extractcompleted">
  `extract.completed`
</h3>

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

<h3 id="extractfailed">
  `extract.failed`
</h3>

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

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

Se envían para los trabajos iniciados con un `webhook` en [`/v2/agent`](/es/features/agent).

<h3 id="agentstarted">
  `agent.started`
</h3>

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

<h3 id="agentaction">
  `agent.action`
</h3>

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>

<h3 id="agentcompleted">
  `agent.completed`
</h3>

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

<h3 id="agentfailed">
  `agent.failed`
</h3>

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

<h3 id="agentcancelled">
  `agent.cancelled`
</h3>

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

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

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.