# Tipos de eventos (/es/webhooks/events)

<!-- agent-signals: reading_time_min: 7 · est_tokens: 3375 · updated: 2026-07-30 -->
Related: [Descripción general](/es/webhooks/overview.md), [Seguridad](/es/webhooks/security.md), [Pruebas](/es/webhooks/testing.md)

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 [#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 [#estructura-del-payload]
</div>

Todos los eventos de webhook comparten esta estructura:

```json
{
  "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 [#eventos-de-rastreo]
</div>

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

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

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

<div id="crawlpage">
  ### `crawl.page` [#crawlpage]
</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
{
  "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` [#crawlcompleted]
</div>

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

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

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

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

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

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

<div id="batch_scrapepage">
  ### `batch_scrape.page` [#batch_scrapepage]
</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
{
  "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` [#batch_scrapecompleted]
</div>

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

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

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

<div id="monitorpage">
  ### `monitor.page` [#monitorpage]
</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 title="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"
  }
}
```

<div id="monitorcheckcompleted">
  ### `monitor.check.completed` [#monitorcheckcompleted]
</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 title="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.

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

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

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

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

<div id="extractcompleted">
  ### `extract.completed` [#extractcompleted]
</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
{
  "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` [#extractfailed]
</div>

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

```json
{
  "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 [#eventos-del-agente]
</div>

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

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

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

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

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

```json
{
  "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` [#agentcompleted]
</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
{
  "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` [#agentfailed]
</div>

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

```json
{
  "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` [#agentcancelled]
</div>

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

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

<div id="event-filtering">
  ## Filtrado de eventos [#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
{
  "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.