linkspect API docs linkspect.com

Monitors and webhooks

A monitor checks a URL for you on a schedule and tells you when something meaningful changes: the site gets blocked at an operator, gets unblocked, is blocked another way, or a browser starts warning about it. You hear about it in two ways, both through the API: a signed POST to your webhook, and the list at GET /v1/events to poll. Without a programmer, you can also get the alerts in Telegram.

Create a monitor

curl https://api.linkspect.com/v1/monitors \
  -H "Authorization: Bearer $LINKSPECT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/",
       "targets": [{"country": "DE", "connection_type": "mobile"}],
       "interval": "15m",
       "webhook_id": "whk_01M74X2KN040MVQJG9T7FGKPWC"}'

When there is an event

For each cohort (country × operator × connection type) the monitor keeps a state: the verdict (ok, blocked, target_down, target_policy) and, for a block, its layer and method. GET /v1/monitors/{id} shows them.

EventMeans
cohort.blockeda cohort became blocked
cohort.unblockedit was blocked and now has another verdict
cohort.block_changedstill blocked, another layer or method
cohort.outcome_changedanother change of verdict, e.g. ok to target_down
cohort.unmeasured / cohort.measuredthree results in a row without a verdict / a verdict again
filter.flagged / filter.cleareda browser or filter started / stopped flagging the site
registry.added / registry.removeda public block list of a country the monitor checks added / removed the site (see below)
monitor.quota_exceededa check was skipped over an account limit (once a day per monitor); limit: "balance" when the balance is used up
webhook.disabledwe stopped sending to a webhook after a day of failures
telegram.disabledwe stopped sending to a Telegram chat: the bot was blocked or removed
account.balance_lowthe balance fell under $2, or under a day of your monitors (see Prices and balance); not tied to a monitor

Public block lists

Each monitor also watches the public block lists of the countries it checks. When a new copy of a list adds the monitor's site you get registry.added; when it no longer has it, registry.removed. Then we check every cohort of the monitor at once (monitor_run: "registry"), so you see which operators actually block the site and how soon. Where the list sets the operators a deadline, we check again when it passes. These checks count against your limits like any other check.

ListsourceDeadlineWe refresh our copy
Gambling register of Poland's Ministry of Financepl.gambling48 hours from the register's entry (due)every 2 hours
CERT Polska warning list (phishing and fraud), applied by Orange, T-Mobile and Playpl.cert_warningnoneabout every 17 hours
List of the Norwegian Gaming Authorityno.gamblingnoneabout every 6 hours

So an event comes at most about 2½ hours after Poland's register changes, about 17½ hours after the CERT Polska list does, and about 6 hours after the Norwegian list does. If we cannot refresh a copy, it goes stale (unknown_stale in results) and makes no events; the next fresh copy is compared with the last one, so a change in between still comes.

{
  "id": "evt_01M7KA0Q5GQ2YB8RZ1D6N0C4WE",
  "type": "registry.added",
  "created_at": "2026-11-17T09:13:05Z",
  "test": false,
  "monitor_id": "mon_01M7K9V3C0ZB6V7W4D7J3T8Q2N",
  "url": "https://casino.example/",
  "registry": {
    "source": "pl.gambling",
    "name": "the gambling register of the Polish Ministry of Finance",
    "country": "PL",
    "entry": "casino.example",
    "listed_on": "2026-11-17",
    "due": "2026-11-19T07:40:00Z",
    "checked_at": "2026-11-17T09:12:41Z"
  }
}

Poll events

curl "https://api.linkspect.com/v1/events?after=evt_01M751NEW0J9MBK551NHH6YN4D" \
  -H "Authorization: Bearer $LINKSPECT_KEY"

Events come oldest first. Keep the id of the last event you handled and pass it as after. Filters: monitor_id, type, since.

Webhooks

curl https://api.linkspect.com/v1/webhooks \
  -H "Authorization: Bearer $LINKSPECT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://hooks.example.com/linkspect", "event_types": ["cohort.blocked", "cohort.unblocked"]}'

The answer has a secret (whsec_…). It is shown only this once: store it. Put the webhook's id into a monitor's webhook_id.

Each event arrives as POST with the event as JSON body, exactly as GET /v1/events lists it, and these headers:

Verify the signature

Use the raw body as received, before any JSON parsing. Refuse a t more than 5 minutes from your clock.

import hashlib, hmac, time

def verify(secret: str, header: str, body: bytes) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t, sig = parts["t"], parts["v1"]
    want = hmac.new(secret.encode(), t.encode() + b"." + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(want, sig) and abs(time.time() - int(t)) <= 300
const crypto = require("node:crypto");

function verify(secret, header, rawBody) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=", 2)));
  const want = Buffer.from(crypto.createHmac("sha256", secret).update(parts.t + "." + rawBody).digest("hex"));
  const got = Buffer.from(parts.v1 || "");
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) <= 300;
  // timingSafeEqual throws when the lengths differ.
  return fresh && got.length === want.length && crypto.timingSafeEqual(want, got);
}
func verify(secret, header string, body []byte) bool {
	var t, sig string
	for _, p := range strings.Split(header, ",") {
		k, v, _ := strings.Cut(p, "=")
		if k == "t" { t = v } else if k == "v1" { sig = v }
	}
	sec, err := strconv.ParseInt(t, 10, 64)
	if err != nil || math.Abs(float64(time.Now().Unix()-sec)) > 300 {
		return false
	}
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(t + "."))
	mac.Write(body)
	return hmac.Equal([]byte(hex.EncodeToString(mac.Sum(nil))), []byte(sig))
}

Answer, retries and repeats

Requests come from linkspect's own server. Your webhook must be an https URL with a host name that resolves to public addresses; we never connect to private, loopback or link-local addresses.

Trying it with a test key

With a lsk_test_… key, monitors and webhooks run on the fixture engine. The host flip.fixtures.linkspect.com is ok during even five-minute windows of UTC and blocked in DNS during odd ones, so a monitor of it with "interval": "15m" produces cohort.blocked and cohort.unblocked events. See Test keys and fixtures.

Use 15m for this. A monitor's checks fall at fixed times: its creation time plus a fixed offset plus whole intervals. Fifteen minutes is three windows, so consecutive checks land on opposite sides. Every longer interval (30m, 1h, the default, and up) is an even number of windows, so every scheduled check sees the same side and no event ever comes. To flip by hand, call POST /v1/monitors/{id}:run in a window of the other side.

For list events, monitor https://registry-flip.fixtures.linkspect.com/ in Poland (PL) or Norway (NO). A test list has this host on it during odd hours of UTC (01:00–02:00, …, 13:00–14:00, …) and not during even ones (12:00–13:00, …). Within a minute of each full hour you get registry.added or registry.removed, and a registry check follows. The hour you create the monitor in is its starting state, so the first event comes at the next full hour. Each of those checks counts in checks_per_day, 24 a day: delete the monitor when you are done. Results of the host in those countries show the listing in their registry field during odd hours. Any interval works: the list events do not depend on the schedule. On a test list the deadline of a Polish listing is never reached, because the host leaves it after an hour.