Les webhooks vous permettent de recevoir des notifications en temps réel sur la progression de vos opérations Firecrawl. Plutôt que de sonder l’état, Firecrawl enverra automatiquement des requêtes HTTP POST vers l’endpoint que vous avez défini lorsque des événements se produisent.

​
Opérations prises en charge

Les webhooks sont disponibles pour la plupart des opérations clés de Firecrawl :
  • Crawl - Recevez des notifications au fil de l’exploration des pages et à la fin du crawl
  • Batch scrape - Recevez des mises à jour pour chaque URL traitée dans un lot
  • Extract - Recevez des mises à jour lorsque les jobs d’extraction démarrent, se terminent ou échouent

​
Configuration rapide

Configurez les webhooks en ajoutant un objet webhook à votre requête :
JSON
{
  "webhook": {
    "url": "https://your-domain.com/webhook",
    "metadata": {
      "any_key": "any_value"
    },
    "events": ["started", "page", "completed", "failed"]
  }
}

​
Options de configuration

ChampTypeRequisDescription
urlstring✅L’URL de votre endpoint de webhook
headersobject❌En-têtes personnalisés à inclure dans les requêtes du webhook
metadataobject❌Données personnalisées incluses dans toutes les charges utiles du webhook
eventsarray❌Types d’événements à recevoir (par défaut : tous les événements)

​
Exemples d’utilisation de base

​
Exploration avec webhook

cURL
curl -X POST https://api.firecrawl.dev/v2/crawl \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -d '{
      "url": "https://docs.firecrawl.dev",
      "limit": 100,
      "webhook": {
        "url": "https://your-domain.com/webhook",
        "metadata": {
          "any_key": "any_value"
        },
        "events": ["started", "page", "completed"]
      }
    }'

​
Scrape par lots avec webhook

cURL
curl -X POST https://api.firecrawl.dev/v2/batch/scrape \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -d '{
      "urls": [
        "https://example.com/page1",
        "https://example.com/page2",
        "https://example.com/page3"
      ],
      "webhook": {
        "url": "https://your-domain.com/webhook",
        "metadata": {
          "any_key": "any_value"
        },
        "events": ["started", "page", "completed"]
      }
    }'

​
Gestion des webhooks

Voici un exemple simple de traitement des webhooks dans votre application : 
import crypto from 'crypto';
import express from 'express';

const app = express();

// Utiliser un parseur de corps brut pour vérifier la signature
app.use('/webhook/firecrawl', express.raw({ type: 'application/json' }));

app.post('/webhook/firecrawl', (req, res) => {
  const signature = req.get('X-Firecrawl-Signature');
  const webhookSecret = process.env.FIRECRAWL_WEBHOOK_SECRET;
  
  if (!signature || !webhookSecret) {
    return res.status(401).send('Non autorisé');
  }
  
  // Extract hash from signature header
  // Extraire le hash de l’en-tête de signature
  if (algorithm !== 'sha256') {
    return res.status(401).send('Algorithme de signature invalide');
  }
  
  // Calculer la signature attendue
  const expectedSignature = crypto
    .createHmac('sha256', webhookSecret)
    .update(req.body)
    .digest('hex');
  
  // Vérifier la signature avec une comparaison sûre au timing
  if (!crypto.timingSafeEqual(Buffer.from(hash, 'hex'), Buffer.from(expectedSignature, 'hex'))) {
    return res.status(401).send('Signature invalide');
  }
  
  // Analyser et traiter le webhook vérifié
  const event = JSON.parse(req.body);
  console.log('Webhook Firecrawl vérifié :', event);
  
  res.status(200).send('ok');
});

app.listen(3000, () => console.log('Écoute sur le port 3000'));

​
Bonnes pratiques

  1. Répondez rapidement – Renvoyez toujours un code d’état 2xx en moins de 30 secondes
  2. Traitez de manière asynchrone – Pour les traitements lourds, mettez le travail en file d’attente et répondez immédiatement
  3. Vérifiez l’authenticité – Vérifiez toujours la signature du webhook (voir Security)