Los webhooks te permiten recibir notificaciones en tiempo real sobre tus operaciones de Firecrawl conforme progresan. En lugar de consultar periódicamente el estado, Firecrawl enviará automáticamente solicitudes HTTP POST a tu punto de conexión especificado cuando se produzcan eventos.

​
Operaciones admitidas

Los webhooks son compatibles con la mayoría de las operaciones principales de Firecrawl:
  • Crawl - Recibe notificaciones a medida que se rastrean las páginas y cuando finalizan los rastreos
  • Batch scrape - Recibe actualizaciones por cada URL extraída en un lote
  • Extract - Recibe actualizaciones cuando los trabajos de extracción se inician, finalizan o fallan

​
Configuración rápida

Configura los webhooks agregando un objeto webhook a tu solicitud:
JSON
{
  "webhook": {
    "url": "https://your-domain.com/webhook",
    "metadata": {
      "any_key": "any_value"
    },
    "events": ["started", "page", "completed", "failed"]
  }
}

​
Opciones de configuración

CampoTipoRequeridoDescripción
urlstring✅La URL del endpoint de tu webhook
headersobject❌Encabezados personalizados para incluir en las solicitudes del webhook
metadataobject❌Datos personalizados incluidos en todas las cargas del webhook
eventsarray❌Tipos de eventos a recibir (por defecto: todos los eventos)

​
Ejemplos de uso básicos

​
Rastreo con 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://tu-dominio.com/webhook",
        "metadata": {
          "any_key": "any_value"
        },
        "events": ["started", "page", "completed"]
      }
    }'

​
Raspado en lote con 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"]
      }
    }'

​
Gestión de webhooks

Aquí tienes un ejemplo sencillo de cómo gestionar webhooks en tu aplicación: 
import crypto from 'crypto';
import express from 'express';

const app = express();

// Usa el analizador de cuerpo en bruto para verificar la firma
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('No autorizado');
  }
  
  // Extrae el hash del encabezado de la firma
  const [algorithm, hash] = signature.split('=');
  if (algorithm !== 'sha256') {
    return res.status(401).send('Algoritmo de firma no válido');
  }
  
  // Calcula la firma esperada
  const expectedSignature = crypto
    .createHmac('sha256', webhookSecret)
    .update(req.body)
    .digest('hex');
  
  // Verifica la firma usando una comparación segura contra ataques de temporización
  if (!crypto.timingSafeEqual(Buffer.from(hash, 'hex'), Buffer.from(expectedSignature, 'hex'))) {
    return res.status(401).send('Firma no válida');
  }
  
  // Analiza y procesa el webhook verificado
  const event = JSON.parse(req.body);
  console.log('Webhook de Firecrawl verificado:', event);
  
  res.status(200).send('ok');
});

app.listen(3000, () => console.log('Escuchando en el puerto 3000'));

​
Mejores prácticas

  1. Responde rápido – Devuelve siempre un código de estado 2xx en menos de 30 segundos
  2. Procesa de forma asíncrona – Para cargas pesadas, encola el trabajo y responde de inmediato
  3. Valida la autenticidad – Verifica siempre la firma del webhook (consulta Seguridad)