Exa Webhooks & Events

概要

Exa ニューラル検索を中心としたイベント駆動型インテグレーションを構築します。Exa はシンクロナスな検索 API（ネイティブ webhook なし）であるため、このスキルは非同期パターンの構築をカバーしています。searchAndContents を使用したスケジュール設定されたコンテンツ監視、findSimilarAndContents を使用した類似性アラート、日付フィルタを使用した新しいコンテンツ検出、webhook スタイルの通知配信などが含まれます。

前提条件

• exa-js がインストールされ、EXA_API_KEY が設定されていること
• キューシステム（BullMQ/Redis）またはcronスケジューラ
• 通知用の webhook エンドポイント

イベントパターン

パターン	メカニズム	ユースケース
コンテンツ監視	startPublishedDate を使用したスケジュール設定 searchAndContents	新しい記事アラート
類似性アラート	定期的な findSimilarAndContents + 差分	競合監視
コンテンツ変更	再検索 + 結果セット比較	更新追跡
リサーチダイジェスト	スケジュール設定された answer + メール/Slack	日次ブリーフィング

手順

ステップ 1: コンテンツ監視サービス

import Exa from "exa-js";
import { Queue, Worker } from "bullmq";

const exa = new Exa(process.env.EXA_API_KEY!);

interface SearchMonitor {
  id: string;
  query: string;
  webhookUrl: string;
  lastResultUrls: Set<string>;
  intervalMinutes: number;
  searchType: "auto" | "neural" | "keyword";
}

const monitorQueue = new Queue("exa-monitors", {
  connection: { host: "localhost", port: 6379 },
});

async function createMonitor(config: Omit<SearchMonitor, "lastResultUrls">) {
  await monitorQueue.add("check-search", config, {
    repeat: { every: config.intervalMinutes * 60 * 1000 },
    jobId: config.id,
  });
  console.log(`Monitor created: ${config.id} (every ${config.intervalMinutes} min)`);
}

ステップ 2: 監視される検索の実行

const worker = new Worker("exa-monitors", async (job) => {
  const monitor = job.data;

  // 前回のチェック以降に公開された新しいコンテンツを検索
  const results = await exa.searchAndContents(monitor.query, {
    type: monitor.searchType || "auto",
    numResults: 10,
    text: { maxCharacters: 500 },
    highlights: { maxCharacters: 300, query: monitor.query },
    // 監視ウィンドウで公開されたコンテンツのみを検索
    startPublishedDate: getLastCheckDate(monitor.id),
  });

  // 本当に新しい結果にフィルタリング
  const newResults = results.results.filter(
    r => !monitor.lastResultUrls?.has(r.url)
  );

  if (newResults.length > 0) {
    await sendWebhook(monitor.webhookUrl, {
      event: "exa.new_results",
      monitorId: monitor.id,
      query: monitor.query,
      timestamp: new Date().toISOString(),
      results: newResults.map(r => ({
        title: r.title,
        url: r.url,
        snippet: r.text?.substring(0, 200),
        highlights: r.highlights,
        publishedDate: r.publishedDate,
        score: r.score,
      })),
    });

    // 追跡済み URL を更新
    await updateLastResultUrls(monitor.id, newResults.map(r => r.url));
  }
}, { connection: { host: "localhost", port: 6379 } });

ステップ 3: 類似性アラートシステム

async function monitorSimilarContent(
  seedUrl: string,
  webhookUrl: string,
  checkIntervalHours = 24
) {
  const results = await exa.findSimilarAndContents(seedUrl, {
    numResults: 5,
    text: { maxCharacters: 300 },
    excludeSourceDomain: true,
    // 前回のチェック期間のコンテンツのみを検索
    startPublishedDate: new Date(
      Date.now() - checkIntervalHours * 60 * 60 * 1000
    ).toISOString(),
  });

  if (results.results.length > 0) {
    await sendWebhook(webhookUrl, {
      event: "exa.similar_content_found",
      seedUrl,
      matchCount: results.results.length,
      matches: results.results.map(r => ({
        title: r.title,
        url: r.url,
        snippet: r.text?.substring(0, 200),
        score: r.score,
      })),
    });
  }

  return results.results.length;
}

ステップ 4: リトライ機能付き Webhook 配信

async function sendWebhook(url: string, payload: any, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(url, {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "X-Exa-Event": payload.event,
        },
        body: JSON.stringify(payload),
      });
      if (response.ok) return;
      console.warn(`Webhook ${response.status}: ${url}`);
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
    }
    await new Promise(r => setTimeout(r, 1000 * Math.pow(2, attempt)));
  }
}

ステップ 5: 日次リサーチダイジェスト

async function generateDailyDigest(
  topics: string[],
  webhookUrl: string
) {
  const digest = [];

  for (const topic of topics) {
    const results = await exa.searchAndContents(topic, {
      type: "neural",
      numResults: 3,
      summary: { query: `Latest developments in: ${topic}` },
      startPublishedDate: new Date(
        Date.now() - 24 * 60 * 60 * 1000
      ).toISOString(),
    });

    digest.push({
      topic,
      articles: results.results.map(r => ({
        title: r.title,
        url: r.url,
        summary: r.summary,
      })),
    });
  }

  await sendWebhook(webhookUrl, {
    event: "exa.daily_digest",
    date: new Date().toISOString().split("T")[0],
    topics: digest,
  });
}

エラーハンドリング

問題	原因	ソリューション
レート制限された監視	同時チェックが多すぎる	監視間隔をずらす
空の結果	日付フィルタが狭すぎる	48時間ウィンドウに拡張
重複アラート	URL 重複排除がない	実行間で結果 URL を追跡
Webhook 配信失敗	エンドポイントがダウン	指数バックオフでリトライ

例

競合インテリジェンス監視の作成

await createMonitor({
  id: "competitor-watch",
  query: "AI code review tools launch announcement",
  webhookUrl: "https://api.myapp.com/webhooks/exa-alerts",
  intervalMinutes: 60,
  searchType: "neural",
});

リソース

• Exa Search Reference
• Exa Find Similar
• BullMQ Documentation

次のステップ

デプロイメント設定については、exa-deploy-integration を参照してください。