Webhook を使用すると、進行中の Firecrawl の処理に関する通知をリアルタイムで受け取れます。ステータス更新をポーリングする代わりに、イベント発生時に Firecrawl が指定したエンドポイントへ自動的に HTTP POST リクエストを送信します。

​
対応しているオペレーション

Webhooks は主要な Firecrawl のオペレーションの大半でサポートされています:
  • Crawl - ページのクロール中およびクロール完了時に通知を受け取る
  • Batch scrape - バッチ内でスクレイプした各 URL の更新を受け取る
  • Extract - 抽出ジョブの開始・完了・失敗時に更新を受け取る

​
クイックセットアップ

リクエストに webhook オブジェクトを追加して、Webhook を設定します：
JSON
{
  "webhook": {
    "url": "https://your-domain.com/webhook",
    "metadata": {
      "any_key": "any_value"
    },
    "events": ["started", "page", "completed", "failed"]
  }
}

​
設定オプション

フィールド型必須説明
urlstring✅Webhook エンドポイントの URL
headersobject❌Webhook リクエストに含めるカスタムヘッダー
metadataobject❌すべての Webhook ペイロードに含めるカスタムデータ
eventsarray❌受信するイベントタイプ（既定: すべてのイベント）

​
基本的な使い方の例

​
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"]
      }
    }'

​
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"]
      }
    }'

​
Webhook のハンドリング

アプリケーションで Webhook を処理するシンプルな例を示します: 
import crypto from 'crypto';
import express from 'express';

const app = express();

// 署名検証のために raw 本文パーサーを使用
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('認証されていません');
  }
  
  // 署名ヘッダーからハッシュを抽出
  const [algorithm, hash] = signature.split('=');
  if (algorithm !== 'sha256') {
    return res.status(401).send('無効な署名アルゴリズム');
  }
  
  // 期待される署名を算出
  const expectedSignature = crypto
    .createHmac('sha256', webhookSecret)
    .update(req.body)
    .digest('hex');
  
  // タイミング安全な比較で署名を検証
  if (!crypto.timingSafeEqual(Buffer.from(hash, 'hex'), Buffer.from(expectedSignature, 'hex'))) {
    return res.status(401).send('無効な署名');
  }
  
  // 検証済みの webhook を解析して処理
  const event = JSON.parse(req.body);
  console.log('検証済みの Firecrawl webhook:', event);
  
  res.status(200).send('ok');
});

app.listen(3000, () => console.log('ポート 3000 で待機中'));

​
ベストプラクティス

  1. 迅速に応答する – 常に 30 秒以内に 2xx ステータスコードを返す
  2. 非同期で処理する – 重い処理はキューに入れ、即時に応答する
  3. 真正性を検証する – 常に Webhook の署名を検証する（Security を参照）