Documentation

How checks work, what alerts contain, and how to integrate.

Getting started

Create an account and confirm your email — that address becomes your first alert channel.
Add domains and pick countries and providers on the onboarding screen.
Connect Telegram under Notifications: press Connect Telegram, open the link, press Start.

How checks work

Each domain is checked from every country and provider (ASN) you selected. A healthy pair is re-checked on the plan’s base interval: every 2 hours on Free, every hour on Starter, every 30 minutes on Pro.

When a check looks wrong, the pair is escalated and re-checked every few minutes — on paid plans through residential exits inside that provider. An alert is sent only after two further checks confirm the problem; alerts confirmed without a residential exit (Free plan) say so. Once three consecutive checks look healthy again, you get a recovery notice and the pair returns to its base interval.

If most providers see a domain as down at the same time, it is reported once as an outage of the domain itself rather than as many separate blocks.

Statuses

Status	Meaning
`live`	Your page loaded (and contains your keyword, if you set one).
`block`	A block notice was served instead of your page, typically by the provider or a regulator.
`captcha`	A challenge page stood between the visitor and your page.
`redirect`	Visitors were sent to a different site.
`unavailable`	The page did not load: DNS, connection or server errors.
`check_failed`	We could not perform the check (for example, no exit was available in that provider). This says nothing about your domain.

Webhooks

Webhook alerts are POST requests with a JSON body and these headers:

X-ASNWatch-Event: incident.confirmed or incident.resolved
X-ASNWatch-Delivery: a UUID that stays the same across retries — use it to ignore duplicates
X-ASNWatch-Signature: sha256=<hex>, an HMAC-SHA256 of the raw body using your webhook secret

Failed deliveries (any non-2xx response) are retried up to 5 times with exponential backoff. Verify the signature before trusting the payload:

$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
if (!hash_equals($expected, $_SERVER['HTTP_X_ASNWATCH_SIGNATURE'] ?? '')) {
    http_response_code(401);
    exit;
}

Public API

Authenticate with an API key in the Authorization header. Keys carry scopes: pairs:read, incidents:read, analytics:read.

curl -H "Authorization: Bearer ak_…" https://asn.watch/api/public/v1/incidents?type=block

Endpoint	Scope	Returns
`GET /api/public/v1/pairs`	`pairs:read`	The status matrix: domains × countries × providers.
`GET /api/public/v1/incidents`	`incidents:read`	Active incidents; filter with `?type=block`, `captcha`, `redirect`, `unavailable` or `origin_outage`.
`GET /api/public/v1/analytics/lifetime`	`analytics:read`	How long domains survive before a block, per country, or per provider with `?country=PL`.

Each key is limited to 60 requests per minute by default. Responses carry X-RateLimit-Limit; when the limit is exceeded you get 429 with Retry-After.