Exa Webhooks & Events

Overview

Build event-driven integrations around Exa neural search. Exa is primarily a synchronous search API at api.exa.ai, so this skill covers async patterns for handling search results, building scheduled content monitoring, and creating webhook-style notification flows around Exa search queries.

Prerequisites

• Exa API key stored in EXA_API_KEY environment variable
• Node.js or Python runtime for scheduled jobs
• Queue system (Redis/BullMQ) for async processing
• Familiarity with Exa search and findSimilar endpoints

Event Patterns

Instructions

Step 1: Set Up Content Monitoring Service

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;
  lastResultIds: string[];
  intervalMinutes: number;
}

const monitorQueue = new Queue("exa-monitors");

async function createMonitor(config: Omit<SearchMonitor, "lastResultIds">) {
  await monitorQueue.add("check-search", config, {
    repeat: { every: config.intervalMinutes * 60 * 1000 },  # 1000: 1 second in ms
    jobId: config.id,
  });
}

Step 2: Execute Monitored Searches

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

  const results = await exa.searchAndContents(monitor.query, {
    type: "neural",
    numResults: 10,
    text: { maxCharacters: 500 },  # HTTP 500 Internal Server Error
    startPublishedDate: getLastCheckDate(monitor.id),
  });

  const newResults = results.results.filter(
    r => !monitor.lastResultIds.includes(r.id)
  );

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

Step 3: Build Similarity Alert System

async function monitorSimilarContent(seedUrl: string, webhookUrl: string) {
  const results = await exa.findSimilarAndContents(seedUrl, {
    numResults: 5,
    text: { maxCharacters: 300 },  # 300: timeout: 5 minutes
    excludeDomains: ["example.com"],
    startPublishedDate: new Date(Date.now() - 86400000).toISOString(),  # 86400000 = configured value
  });

  if (results.results.length > 0) {
    await sendWebhook(webhookUrl, {
      event: "exa.similar_content_found",
      seedUrl,
      matches: results.results,
    });
  }
}

Step 4: Webhook Delivery with Retry

async function sendWebhook(url: string, payload: any, retries = 3) {
  for (let attempt = 0; attempt < retries; attempt++) {
    try {
      const response = await fetch(url, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(payload),
      });
      if (response.ok) return;
    } catch (error) {
      if (attempt === retries - 1) throw error;
      await new Promise(r => setTimeout(r, 1000 * Math.pow(2, attempt)));  # 1000: 1 second in ms
    }
  }
}

Error Handling

Examples

Competitive Intelligence Monitor

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

Resources

• Exa API Documentation
• Exa JavaScript SDK

Next Steps

For deployment setup, see exa-deploy-integration.

Output

• Configuration files or code changes applied to the project
• Validation report confirming correct implementation
• Summary of changes made and their rationale