Types d’é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.

Référence rapide

É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

Structure du payload

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

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

Événements de crawl

`crawl.started`

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

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

`crawl.page`

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

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

`crawl.completed`

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

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

Événements de scraping par lot

`batch_scrape.started`

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

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

`batch_scrape.page`

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

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

`batch_scrape.completed`

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

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

Événements de Monitor

`monitor.page`

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.

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`

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.

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

Événements d’extraction

`extract.started`

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

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

`extract.completed`

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.

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

`extract.failed`

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

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

Événements des agents

Envoyés pour les tâches démarrées avec un webhook sur /v2/agent.

`agent.started`

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

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

`agent.action`

Envoyé après chaque exécution d’un outil (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": {}
}

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.

`agent.completed`

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.

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

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

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

`agent.cancelled`

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

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

Filtrage des événements

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 :

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

Prise en main

Points de terminaison de base

Plus

Démarrages rapides

Guides développeur

Webhooks

Cas d'utilisation

Autres

Contribuer

Types d’événements

Référence rapide

Structure du payload

Événements de crawl

`crawl.started`

`crawl.page`

`crawl.completed`

Événements de scraping par lot

`batch_scrape.started`

`batch_scrape.page`

`batch_scrape.completed`

Événements de Monitor

`monitor.page`

`monitor.check.completed`

Événements d’extraction

`extract.started`

`extract.completed`

`extract.failed`

Événements des agents

`agent.started`

`agent.action`

`agent.completed`

`agent.failed`

`agent.cancelled`

Filtrage des événements

​Référence rapide

​Structure du payload

​Événements de crawl

​crawl.started

​crawl.page

​crawl.completed

​Événements de scraping par lot

​batch_scrape.started

​batch_scrape.page

​batch_scrape.completed

​Événements de Monitor

​monitor.page

​monitor.check.completed

​Événements d’extraction

​extract.started

​extract.completed

​extract.failed

​Événements des agents

​agent.started

​agent.action

​agent.completed

​agent.failed

​agent.cancelled

​Filtrage des événements

Référence rapide

Structure du payload

Événements de crawl

`crawl.started`

`crawl.page`

`crawl.completed`

Événements de scraping par lot

`batch_scrape.started`

`batch_scrape.page`

`batch_scrape.completed`

Événements de Monitor

`monitor.page`

`monitor.check.completed`

Événements d’extraction

`extract.started`

`extract.completed`

`extract.failed`

Événements des agents

`agent.started`

`agent.action`

`agent.completed`

`agent.failed`

`agent.cancelled`

Filtrage des événements