How it checks

A watch is a promise to look, not a promise to keep asking. Watch knows several ways to find out whether something changed, and it always takes the cheapest one the source allows.

The order

An event or a webhook — when the thing can push to Watch, nothing is polled at all. An event watch is checked when its OpenVibe.Events event arrives; a webhook watch gets its own signed /hooks/ address and is checked when a delivery reaches it.
The site's own ETag or Last-Modified — if the site gave one, the check carries If-None-Match/If-Modified-Since. A 304 Not Modified means “no change” and no body is read.
A feed — an RSS or Atom feed is read before the page it describes, and the feed's own conditional headers apply.
An API — a JSON endpoint is read the same way, mapped by the watch itself.
A page — the page's text is read, as the whole body or one element.
Your own computer — for something on your home or office network (a router, a NAS, a printer page), one read-only check from your own machine through the OpenVibe Node, only where you turned that on for it.
An expensive browser check through OpenVibe.Run — the last resort. It waits for a browser worker, so a run watch is accepted but not checked yet, and says so on its page.

The manners

Per-site spacing. No two requests to one host are made at once, and none closer together than the host's minimum interval — whatever the watch says.
Never faster than the cadence. A watch is due on the cadence you choose (the shortest here is 15 minutes). A failing site is checked less and less often (backoff), up to a cap.
When the site asks you to wait. A 429 or 503 with Retry-After is obeyed: the watch is not checked again before that time, and the check is recorded “the site asked us to wait”.
Conditional outcomes cost nothing. A 304 or a body identical to the last one records no observation — but the condition is still evaluated, so “this has been true for five minutes” can fire while nothing moved.

What a check state means

State	In plain words
`ok`	Read, and nothing changed since the last reading.
`not_modified`	The site said “not modified” — no body was read.
`no_change`	The body was read and was identical to last time.
`changed`	The value changed.
`condition_met`	The condition fired (and a notification was emitted).
`http_error`	The site answered an error.
`timeout`	The site did not answer in time.
`parse_error`	The answer could not be read as what the watch expected.
`rate_limited`	The site asked Watch to wait.
`budget_exceeded`	The watch's own budget was reached.
`skipped`	This kind of check is not run yet (or an AI reading is not supported yet). Nothing was fetched.
`disabled`	The watch is paused, disabled or failing, so it was not checked.

What is honest about it

A value the source did not state is null; Watch never invents one, and an absent value stays absent.
A failed check is a recorded state, never a silent skip; a failed check records no observation.
A site that is unavailable is retried with backoff, not hammered.
The kinds that arrive later (event, webhook, Run, Node) and an AI reading are not offered in the form, because Watch will not pretend to check what it cannot.

Start a watch · Back home