Alerts

What an alert is

An alert isn’t a new kind of data — it’s the diff on top of the runs you already have. Every time a dimension checks in, CompetLab compares the fresh reading to the previous one and, when the two differ enough to matter, turns that gap into a short, readable note. So the same run that updates a dashboard can also reach you the moment it lands, without you sitting on the page.

Each alert is built to be understood at a glance, not decoded:

The “why it matters” line is the part that makes an alert worth reading. A competitor cutting a price is a fact; you’re now the most expensive option in the market is the reason you’d act on it. CompetLab writes that second sentence for you.

What an alert looks like

A few alerts from a single day read something like this — the severity marker, the dimension and who it’s about, the change in plain words, and the “so what” that follows:

Because every alert links back to the run it came from, the expandable view underneath a row is the real evidence — the specific pages, prices, or ranks that moved — not a paraphrase. You read the headline, and drill down only when you want the receipts.

How urgent it is

Every alert carries one of four severity levels, so a genuine threat and a routine tick never look the same in the list:

Severity is also what your notification channels filter on: you can tell a channel to only speak up at High and above and leave the quieter movements to the in-app list. That keeps the signal where you want it loud and the noise where you can scan it later.

Getting them where you work

Alerts live in the app, but they don’t have to stay there. Route them to any of four channels, and give each one its own severity threshold — the floor it fires at — and its own delivery frequency, so an urgent Slack ping and a tidy weekly email can run side by side off the same alerts. Not every channel offers every cadence — email is digest-only, and a webhook fires immediately (see the table).

The pairing is the point: a channel set to Critical + immediate interrupts you only for the things that can’t wait, while the same account’s Info + weekly channel gives you a calm Monday-morning recap of everything else. Set the threshold high and the frequency low, and a channel goes quiet without going dark.

Reading and filtering the list

In the app, alerts are grouped by date so the newest movement sits on top and you can see a day’s worth of change together. Three filters narrow the view: by dimension, to focus on just pricing or just content; by competitor, to follow one rival’s moves; and by severity, to pull only the critical ones to the front. The same filters are available on the Alerts API if you’d rather query them from code.

Alerts are raised on the schedule each dimension already runs on — turning dimensions on or off and setting their cadence is covered in How monitoring works, not here. This page is about what an alert is and where it goes once it’s raised.

Wiring up a webhook

The webhook channel turns alerts into an HTTP feed you can pipe into anything — a bot you built, an incident tool, a queue, an n8n flow. Add a URL in your project’s notification settings, give it a severity threshold, and CompetLab POSTs to it the moment a monitoring run raises alerts that clear the bar. It’s immediate-only — there’s no digest for webhooks.

The payload. Each delivery is a single application/json POST. One request carries all the alerts from one dimension’s run, under a small envelope:

{
  "version": 2,
  "event": "alerts.created",
  "timestamp": "2026-07-11T14:05:00.000Z",
  "projectId": "65a1b2c3d4e5f6a7b8c9d0e1",
  "projectName": "Acme",
  "organizationId": "65a1b2c3d4e5f6a7b8c9d0e2",
  "runId": "65a1b2c3d4e5f6a7b8c9d0e3",
  "dimension": "ai-visibility",
  "alerts": [
    {
      "id": "65a1b2c3d4e5f6a7b8c9d0e4",
      "severity": "medium",
      "title": "Your AI Visibility Score on Claude rose from 0 to 72",
      "actionHint": "Reinforce the pages that lifted you — they're working.",
      "competitorDomain": "acme.com",
      "alertType": null,
      "gapWarnings": [],
      "context": { "ai-visibility": { "scoreFrom": 0, "scoreTo": 72 } },
      "createdAt": "2026-07-11T14:05:00.000Z"
    }
  ]
}

dimension is the canonical slug — one of ai-visibility, positioning, pricing, content, or tech-trust — and each alert’s context is keyed by that same slug, carrying the dimension-specific before/after figures the alert was raised from (the same numbers you see when you expand the alert in the app). severity is one of critical, high, medium, or info; alertType and createdAt may be null, and gapWarnings is always an array. There’s no top-level message or deep-link field — the human-readable text is title plus actionHint.

Verifying it’s really from CompetLab. Set a signing secret on the channel and every request carries an X-CompetLab-Signature-256 header — sha256= followed by the HMAC-SHA256 of the raw request body, keyed by your secret. Recompute it over the untouched body and compare before you trust a payload:

import crypto from 'node:crypto'
 
function isFromCompetLab(rawBody, signatureHeader, secret) {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex')
  return crypto.timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected))
}

If your receiver authenticates a different way, you can instead set a custom header (say X-API-Key) that CompetLab sends verbatim with each request.

Delivery. CompetLab waits up to 10 seconds for a 2xx, and retries a failed delivery up to three times with a 1s / 2s / 4s backoff. A 400, 403, 404, or 410 reads as a permanent misconfiguration — no retry, and the channel is switched off with the error recorded, so you can fix the endpoint and turn it back on. Delivery is best-effort and at-most-once: alerts raised while a channel is off aren’t replayed when you re-enable it, so treat the webhook as a live feed, not a system of record — the Alerts API is there when you need to reconcile the full list.

Work with it in code

Every alert is available programmatically — the same list the app renders, with the same filters.