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 });
  }

  // Payload: { event: "watch.fired", watch_id, trigger, delta,
  //            current_response, previous_response, run_id, diff_summary }
  const { delta, watch_id, diff_summary } = JSON.parse(body);

  // delta.rank_changes = [{ brand, from_rank, to_rank }, ...]
  // Alert only on drops of 2+ positions (to_rank is WORSE when higher).
  const drops = (delta?.rank_changes ?? [])
    .filter((rc) => typeof rc.from_rank === "number" && typeof rc.to_rank === "number" && rc.to_rank > rc.from_rank + 1)
    .map((rc) => `${rc.brand}: ${rc.from_rank} -> ${rc.to_rank}`);

  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} (${diff_summary}):\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.