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"}'
url,targets,check_type,profile,contentandbrowserwork as inPOST /v1/checks.interval:15m,30m,1h(default),6h,12hor24h. Adeepmonitor needs at least1h.- The first check runs within a minute, then every interval. Each one is
an ordinary check: you see it in
GET /v1/checkswithmonitor_idandmonitor_run, and it counts in your account's daily limits (see Limits and usage). The account'smonitorslimit counts test and live monitors together. POST /v1/monitors/{id}:runruns one now, outside the schedule.PATCHchanges a monitor ("paused": truestops it),DELETEremoves it.
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.
- The first verdict is the starting state. It is not an event.
- When a check sees a different verdict, we check those cohorts again at
once (
monitor_run: "confirmation"). Only when the second measurement agrees does the state change and an event appear. A one-off glitch makes no event. If the confirmation cannot run, for example because today's limit is used up, the next scheduled check confirms instead. - Results without a verdict, such as a failure of our vantage point, do not
change the state. After three in a row you get
cohort.unmeasured, andcohort.measuredwhen a verdict is back. - Browser warnings and other filters outside the operators' networks
change after two scheduled checks in a row agree:
filter.flagged,filter.cleared.
| Event | Means |
|---|---|
cohort.blocked | a cohort became blocked |
cohort.unblocked | it was blocked and now has another verdict |
cohort.block_changed | still blocked, another layer or method |
cohort.outcome_changed | another change of verdict, e.g. ok to target_down |
cohort.unmeasured / cohort.measured | three results in a row without a verdict / a verdict again |
filter.flagged / filter.cleared | a browser or filter started / stopped flagging the site |
registry.added / registry.removed | a public block list of a country the monitor checks added / removed the site (see below) |
monitor.quota_exceeded | a check was skipped over an account limit (once a day per monitor); limit: "balance" when the balance is used up |
webhook.disabled | we stopped sending to a webhook after a day of failures |
telegram.disabled | we stopped sending to a Telegram chat: the bot was blocked or removed |
account.balance_low | the 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.
| List | source | Deadline | We refresh our copy |
|---|---|---|---|
| Gambling register of Poland's Ministry of Finance | pl.gambling | 48 hours from the register's entry (due) | every 2 hours |
| CERT Polska warning list (phishing and fraud), applied by Orange, T-Mobile and Play | pl.cert_warning | none | about every 17 hours |
| List of the Norwegian Gaming Authority | no.gambling | none | about 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"
}
}
listed_onis the date the list gives; the Norwegian list gives none.dueis only onregistry.addedof a list with a deadline.entryis the name on the list. It is the monitor's host, or a parent of it where an operator blocks the names under a listed name too. We match names exactly as theregistryfield of results does, for the same operators. A result names one list per cohort, a binding one first, so when the site is on two lists it may name the other one. After aregistry.addedofpl.gambling, results showstatus: "pending"untildue, thenlisted.- The copy that is current when you create the monitor is its starting
state, not an event: a site that was already listed then shows in the
results'
registryfield instead. Changing the URL or targets starts over from the copy of that moment. - A paused monitor takes new copies as they are, without events or checks.
- Lists that are not public never make events.
- A webhook with no
event_typesgets every type, these new ones included. To keep only the old ones, list them.
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:
Linkspect-Signature: t=1762856112,v1=5257a869…: the time of sending (Unix seconds) and the HMAC-SHA256, keyed with your secret, oft, a dot and the raw body.Linkspect-Event-Id,Linkspect-Event-Type,Linkspect-Delivery-Id,Linkspect-Attempt.
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
- Answer with any
2xxwithin 10 seconds. Do the work after answering. - Anything else (an error, a timeout, a redirect: we never follow redirects) is retried after 1, 5 and 15 minutes, then 1, 2, 4, 8 and 8 hours: 9 attempts over about 23 hours.
- A retry carries the same event and
Linkspect-Event-Idwith a new signature. You may also get an event twice in rare cases, so drop repeats by the event ID. - Every attempt is listed at
GET /v1/webhooks/{id}/deliverieswith the status code or the error. - After 24 hours of only failures we disable the webhook and write
webhook.disabled.POST /v1/webhooks/{id}:enableturns it on again; get what you missed fromGET /v1/events.
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.