Loading...
← Other blogs

AI Tools

An API for monitoring web pages: your first monitor in five steps

Create a monitor, describe the change, read the event. The loop is smaller than it sounds.

• 3 min read

An API for monitoring web pages lets a program ask a service to watch a URL and tell it when the content changes. You do not fetch the page yourself, you do not store a copy to compare against, and you do not write the part that decides whether a difference matters. You create a monitor, and events arrive at an address you choose.

The idea in five steps

  1. You describe what to watch. A URL for a page, plain text for a subject, or a source object for one public feed.
  2. You say what counts as a change, in a sentence. "Tell me when this page adds a region" is a valid rule.
  3. The service fetches on an interval you set and compares.
  4. When the rule matches, it posts an event to your webhook.
  5. Your code checks the signature, stores the event and does something with it.

That is the whole loop. Everything else is detail about the payload.

Creating one, in words

The reference is at ayewatch.ai/documentation, and the shape is small. The base is https://ayewatch.ai/api/v1, and the whole surface is five calls: one each to create, list, read, update and remove a monitor. A create request carries a name, a kind, an interval, a description and an active flag.

The description is where a beginner should spend the most time, because it is the rule. A vague description produces vague alerts.

What arrives at your webhook

The first event is worth reading before you point anything at production, and a request bin is the cheapest way to see it. Expect:

  • topic_id, which monitor fired.
  • update_id, unique per update. Store it.
  • headline, a short summary written for a person.
  • content and content_detail, the body of what changed.
  • created_at, in ISO 8601.
  • score and novelty_class, where the service provides them.
  • Quotes with source URLs, so a reviewer can confirm the claim.

Then comes proof of origin. The X-AyeWatch-Signature header holds an HMAC-SHA256 digest computed over the raw body with a secret shared between the service and you. Recompute it, compare without leaking timing, and refuse the request when the two differ.

expected = hmac_sha256(secret, raw_body)
if not constant_time_equal(expected, header):
    reject

The three mistakes beginners make

One monitor for a whole site. When it fires, nobody knows which page moved. One page per monitor keeps the history readable.

A handler that does real work. Deliveries time out after 10 seconds and are retried up to 10 times with backoff. Acknowledge, queue, process later.

Order is not guaranteed. Two events can land in reverse, so index created_at and treat it as the sequence rather than the arrival time.

What it will not do

It watches public sources. A page behind a login, a dashboard, a bot wall: none of those are in scope. It also does not act for you. The event says what changed, not what to do about it.

Push and the feed are on every plan. Email, Slack, Discord, webhooks and the API are paid features, billed in monitoring credits, with paid plans from $9 a month and a 7 day trial.

A first project that teaches the shape

Pick a public page you already check by hand, such as a status page or a pricing page. Create one monitor with a one-line description. Send its events to a request bin. Read the payload, then write a ten-line receiver that verifies the signature and prints the headline.

When that works, you understand the API. Every later integration is the same shape with a different reaction.

Originally published on claudegpt.si