Rank-drop alerts

Alert your team when brand rank drops by 2+ positions on any AI surface. Combine /v1/watch with a server-side filter so you only page on real movement, not noise.

Create the watch

bash

curl https://api.mentionsapi.com/v1/watch \
  -H "Authorization: Bearer lvk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "best CRM for small business",
    "brand": "HubSpot",
    "mode": "all_live",
    "interval": "daily",
    "webhook_url": "https://your-app.com/webhooks/rank-drop",
    "webhook_secret": "whsec_at_least_16_chars",
    "trigger_on": ["rank_changed"]
  }'

Filter to real drops only

The webhook fires on every rank_changed trigger; filter to drops of 2+ positions on your side to keep the signal-to-noise low.

javascript

import { createHmac, timingSafeEqual } from "node:crypto";

export async function POST(req: Request) {
  const body = await req.text();
  const sig = req.headers.get("x-mentionsapi-signature") ?? "";
  const computed = createHmac("sha256", process.env.MENTIONS_WEBHOOK_SECRET!).update(body).digest("hex");
  if (!timingSafeEqual(Buffer.from(sig), Buffer.from(computed))) {
    return new Response("bad signature", { status: 401 });
  }

  const { results, prev_results, watch_id } = JSON.parse(body);

  // Compute per-surface rank delta and alert on drops of 2+ positions.
  const drops: string[] = [];
  for (const surface of Object.keys(results.providers)) {
    const newRank = results.providers[surface]?.rank;
    const oldRank = prev_results?.providers[surface]?.rank;
    if (typeof newRank === "number" && typeof oldRank === "number" && newRank > oldRank + 1) {
      drops.push(`${surface}: ${oldRank} -> ${newRank}`);
    }
  }

  if (drops.length > 0) {
    await fetch(process.env.SLACK_WEBHOOK_URL!, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ text: `Rank drops on watch ${watch_id}:\n${drops.join("\n")}` }),
    });
  }

  return new Response("ok");
}

Cost

Daily mode:all_live watch = $0.50/day = $15/month per query. Webhook delivery is free.