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

# Types d’événements

> Référence des événements webhook

Firecrawl envoie des événements webhook à chaque étape du cycle de vie d’une tâche, afin que vous puissiez suivre la progression, récupérer les résultats et gérer les échecs en temps réel sans avoir à interroger l’API en continu.

<div id="quick-reference">
  ## Référence rapide
</div>

| Événement                 | Déclencheur                                                                                      |
| ------------------------- | ------------------------------------------------------------------------------------------------ |
| `crawl.started`           | La tâche de crawl commence son traitement                                                        |
| `crawl.page`              | Une page est extraite pendant un crawl                                                           |
| `crawl.completed`         | La tâche de crawl se termine et toutes les pages ont été traitées                                |
| `batch_scrape.started`    | La tâche d’extraction par lot commence son traitement                                            |
| `batch_scrape.page`       | Une URL est extraite pendant une extraction par lot                                              |
| `batch_scrape.completed`  | Toutes les URL du lot ont été traitées                                                           |
| `extract.started`         | La tâche d’extraction commence son traitement                                                    |
| `extract.completed`       | L’extraction se termine avec succès                                                              |
| `extract.failed`          | L’extraction échoue                                                                              |
| `agent.started`           | La tâche de l’agent commence son traitement                                                      |
| `agent.action`            | L’agent exécute un outil (scrape, search, etc.)                                                  |
| `agent.completed`         | L’agent se termine avec succès                                                                   |
| `agent.failed`            | L’agent rencontre une erreur                                                                     |
| `agent.cancelled`         | La tâche de l’agent est annulée par l’utilisateur                                                |
| `monitor.page`            | L’extraction d’une page surveillée se termine                                                    |
| `monitor.check.completed` | La vérification du monitor se termine et les modifications au niveau de la page sont disponibles |

<div id="payload-structure">
  ## Structure du payload
</div>

Tous les événements webhook ont la même structure :

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

| Champ      | Type            | Description                                                      |
| ---------- | --------------- | ---------------------------------------------------------------- |
| `success`  | boolean         | Indique si l’opération a réussi                                  |
| `type`     | string          | Type d’événement (par exemple `crawl.page`)                      |
| `id`       | string          | ID de la tâche                                                   |
| `data`     | array ou object | Données spécifiques à l’événement (voir les exemples ci-dessous) |
| `metadata` | object          | Métadonnées personnalisées de la configuration de votre webhook  |
| `error`    | string          | Message d’erreur (lorsque `success` est `false`)                 |

<div id="crawl-events">
  ## Événements de crawl
</div>

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

Envoyé lorsque la tâche de crawl commence son traitement.

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

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

Envoyé pour chaque page extraite. Le tableau `data` contient le contenu de la page et ses métadonnées.

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

Envoyé lorsque la tâche de crawl est terminée et que toutes les pages ont été traitées.

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

<div id="batch-scrape-events">
  ## Événements de scraping par lot
</div>

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

Envoyé lorsque la tâche d’extraction par lots commence son traitement.

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

Envoyé pour chaque URL individuelle extraite. Le tableau `data` contient le contenu de la page et ses métadonnées.

```json theme={null}
{
  "success": true,
  "type": "batch_scrape.page",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [
    {
      "markdown": "# Page content...",
      "metadata": {
        "title": "Page Title",
        "description": "Page description",
        "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>

Envoyé lorsque toutes les URL du lot ont été traitées.

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

<div id="monitor-events">
  ## Événements de Monitor
</div>

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

Envoyé lorsque le scrape de chaque page surveillée est terminé. Cet événement est émis par le worker de scrape ; il arrive donc avant que la vérification complète du monitor ne soit consolidée.

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

Envoyé lorsqu’une vérification de monitor se termine. L’objet `data` contient l’état de la vérification ainsi que des totaux récapitulatifs. Les résultats par page sont uniquement envoyés via les événements `monitor.page` ou renvoyés par l’API de vérification du 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` vaut `true` lorsque la vérification s’est terminée sans erreur de page. Pour les vérifications partielles ou en échec, `success` vaut `false` et `error` peut contenir un message.

<div id="extract-events">
  ## Événements d’extraction
</div>

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

Envoyé lorsque la tâche d’extraction commence à être traitée.

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

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

Envoyé lorsqu’une opération d’extraction s’achève avec succès. Le tableau `data` contient les données extraites et les informations d’utilisation.

```json theme={null}
{
  "success": true,
  "type": "extract.completed",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [
    {
      "success": true,
      "data": { "siteName": "Site exemple", "category": "Technologie" },
      "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>

Envoyé lorsqu’une extraction échoue. Le champ `error` contient la raison de l’échec.

```json theme={null}
{
  "success": false,
  "type": "extract.failed",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [],
  "error": "Échec de l'extraction des données : délai d'attente dépassé",
  "metadata": {}
}
```

<div id="agent-events">
  ## Événements de l’agent
</div>

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

Envoyé lorsque la tâche de l’agent commence à être traitée.

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

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

Envoyé après chaque exécution d’un outil (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>
  La valeur `creditsUsed` dans les événements `action` est une **estimation** du total
  de crédits utilisés jusqu'à présent. Le décompte
  final et exact des crédits n'est disponible que dans les événements `completed`, `failed`
  ou `cancelled`.
</Note>

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

Envoyé lorsque l'agent a terminé avec succès. Le tableau `data` contient les données extraites et le total des crédits consommés.

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

Envoyé lorsque l’agent rencontre une erreur. Le champ `error` contient le motif de l’échec.

```json theme={null}
{
  "success": false,
  "type": "agent.failed",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [
    {
      "creditsUsed": 8
    }
  ],
  "error": "Crédits maximum dépassés",
  "metadata": {}
}
```

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

Envoyé lorsque la tâche de l’agent est annulée par l’utilisateur.

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

<div id="event-filtering">
  ## Filtrage des événements
</div>

Par défaut, vous recevez tous les événements. Pour vous abonner uniquement à certains événements, indiquez un tableau `events` dans la configuration de votre webhook :

```json theme={null}
{
  "url": "https://your-app.com/webhook",
  "events": ["completed", "failed"]
}
```

C'est utile si vous vous intéressez uniquement à l'achèvement de la tâche et n'avez pas besoin de mises à jour pour chaque page.