Webhooks permitem que você receba notificações em tempo real sobre suas operações no Firecrawl, à medida que progridem. Em vez de consultar periodicamente por atualizações de status, o Firecrawl enviará automaticamente solicitações HTTP POST para o endpoint especificado quando eventos ocorrerem.

​
Operações compatíveis

Webhooks são compatíveis com a maioria das principais operações do Firecrawl:
  • Crawl - Seja notificado à medida que as páginas são rastreadas e quando os crawls forem concluídos
  • Batch scrape - Receba atualizações para cada URL raspada em um lote
  • Extract - Receba atualizações quando tarefas de extração iniciarem, concluírem ou falharem

​
Configuração rápida

Configure webhooks adicionando um objeto webhook à sua requisição:
JSON
{
  "webhook": {
    "url": "https://your-domain.com/webhook",
    "metadata": {
      "any_key": "any_value"
    },
    "events": ["started", "page", "completed", "failed"]
  }
}

​
Opções de configuração

CampoTipoObrigatórioDescrição
urlstring✅URL do endpoint do seu webhook
headersobject❌Cabeçalhos personalizados para incluir nas requisições do webhook
metadataobject❌Dados personalizados incluídos em todas as cargas do webhook
eventsarray❌Tipos de evento a receber (padrão: todos os eventos)

​
Exemplos de uso básico

​
Rastreamento com 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": ["iniciado", "página", "concluído"]
      }
    }'

​
Raspagem em lote com 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"]
      }
    }'

​
Manipulando webhooks

Aqui está um exemplo simples de como lidar com webhooks na sua aplicação: 
import crypto from 'crypto';
import express from 'express';

const app = express();

// Use o parser de corpo bruto para verificar a assinatura
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('Não autorizado');
  }
  
  // Extraia o hash do cabeçalho de assinatura
  const [algorithm, hash] = signature.split('=');
  if (algorithm !== 'sha256') {
    return res.status(401).send('Algoritmo de assinatura inválido');
  }
  
  // Calcule a assinatura esperada
  const expectedSignature = crypto
    .createHmac('sha256', webhookSecret)
    .update(req.body)
    .digest('hex');
  
  // Verifique a assinatura usando comparação com segurança temporal
  if (!crypto.timingSafeEqual(Buffer.from(hash, 'hex'), Buffer.from(expectedSignature, 'hex'))) {
    return res.status(401).send('Assinatura inválida');
  }
  
  // Analise e processe o webhook verificado
  const event = JSON.parse(req.body);
  console.log('Webhook do Firecrawl verificado:', event);
  
  res.status(200).send('ok');
});

app.listen(3000, () => console.log('Escutando na porta 3000'));

​
Melhores práticas

  1. Responda rapidamente – Sempre retorne um código de status 2xx em até 30 segundos
  2. Processe de forma assíncrona – Para cargas pesadas, coloque o trabalho em uma fila e responda imediatamente
  3. Valide a autenticidade – Sempre verifique a assinatura do webhook (consulte Segurança)