Automated Website Monitoring with Screenshots
Scheduled screenshots, pixel and text change detection, alerts and retention: a practical blueprint for visual website monitoring.
Uptime checks tell you a server answered. They don't tell you the pricing table disappeared, a CSS deploy broke the mobile navigation, or a third-party widget now covers the checkout button. Visual monitoring fills that gap: capture the page on a schedule, compare it with the last version you accepted, and alert when it changes in a way that matters.
This guide builds that loop with the Screenshotly API as the capture step. Screenshotly renders the page and returns the capture. The scheduling, history, comparison and alerting are yours, and the code below shows each part.
What visual monitoring catches
HTTP status checks pass while:
- a CSS or JavaScript deploy breaks the layout
- a JavaScript error leaves a section blank
- a third-party script (chat, consent or A/B testing) covers content
- the mobile layout breaks while desktop is fine
- copy, prices or legal text change without anyone noticing
Visual monitoring doesn't replace uptime monitoring, error tracking or real-user monitoring. It catches a different class of failure, and it works best alongside them.
The monitoring loop
| Step | Who does it | Notes |
|---|---|---|
| Schedule a check | You: cron, a worker, CI schedule | Screenshotly has no scheduler |
| Capture the page or zone | Screenshotly | Image (all plans) or rendered HTML (Basic+) |
| Store the capture | You: disk or object storage | Keep the accepted baseline plus history |
| Compare with the baseline | You: pixelmatch, text diff | Mask or skip noisy regions |
| Confirm and alert | You: Slack, email, incident tool | Re-capture once before alerting |
| Accept a new baseline | You: a person approves | Expected changes become the new baseline |
Step 1: choose a frequency your quota can sustain
Monthly captures = pages × devices × checks per day × 30. Add 5–10% headroom for confirmation re-captures. Failed captures don't count toward your quota.
| Setup | Monthly captures | Smallest plan that fits |
|---|---|---|
| 10 pages, desktop only, daily | 10 × 1 × 1 × 30 = 300 | Basic (2,500/mo) |
| 20 pages, desktop + mobile, every 6 hours | 20 × 2 × 4 × 30 = 4,800 | Growth (12,000/mo) |
| 10 critical pages, desktop, every 15 minutes | 10 × 1 × 96 × 30 = 28,800 | Scale (50,000/mo) |
| 50 pages, desktop, hourly | 50 × 1 × 24 × 30 = 36,000 | Scale (50,000/mo) |
The Free plan includes 100 captures in total, not per month. It is enough to build and test the pipeline, but not to run it. There is no automatic overage, so a check that runs out of quota fails instead of billing you. Plan your headroom with that in mind. See pricing for current limits.
Rate limits matter too. Checking 50 pages at the top of every hour means 50 requests in a burst. That fits within Scale's 200 requests per minute. On Basic (40/min) or Growth (80/min), spread the checks across the hour, or queue them as async jobs.
Step 2: capture and compare
This script runs on a long-lived worker using node-cron v4. noOverlap skips a tick if the previous run is still going, and timezone: 'UTC' avoids gaps around daylight-saving changes. It captures each page, skips the pixel diff when the file is byte-identical to the baseline, and otherwise compares with pixelmatch.
// monitor.mjs (Node 18+)
import cron from 'node-cron';
import { createHash } from 'node:crypto';
import { mkdir, readFile, writeFile } from 'node:fs/promises';
import pixelmatch from 'pixelmatch';
import { PNG } from 'pngjs';
const PAGES = [
{ id: 'home', url: 'https://www.example.com/', maxRatio: 0.01 },
{ id: 'pricing', url: 'https://www.example.com/pricing', maxRatio: 0.002 },
{ id: 'login', url: 'https://www.example.com/login', maxRatio: 0.005 },
];
async function capture(body) {
const res = await fetch('https://screenshotly.app/api/screenshot', {
method: 'POST',
headers: { 'x-api-key': process.env.SCREENSHOTLY_API_KEY, 'Content-Type': 'application/json' },
body: JSON.stringify(body),
});
if (!res.ok) {
const err = await res.json().catch(() => ({}));
throw new Error(`${res.status} ${err.error ?? ''} ${err.message ?? ''}`);
}
return Buffer.from(await res.arrayBuffer());
}
const sha256 = (buf) => createHash('sha256').update(buf).digest('hex');
function diffRatio(baseline, current) {
const a = PNG.sync.read(baseline);
const b = PNG.sync.read(current);
if (a.width !== b.width || a.height !== b.height) return { ratio: 1, diff: null };
const diff = new PNG({ width: a.width, height: a.height });
const mismatched = pixelmatch(a.data, b.data, diff.data, a.width, a.height, { threshold: 0.1 });
return { ratio: mismatched / (a.width * a.height), diff: PNG.sync.write(diff) };
}
async function checkPage(page) {
const body = { url: page.url, device: 'desktop', format: 'png', fullPage: true, waitForNetworkIdle: true };
const current = await capture(body);
const baselinePath = `baselines/${page.id}.png`;
const baseline = await readFile(baselinePath).catch(() => null);
if (!baseline) {
await writeFile(baselinePath, current); // first run: accept as baseline
return;
}
if (sha256(baseline) === sha256(current)) return; // byte-identical: nothing to diff
const { ratio, diff } = diffRatio(baseline, current);
if (ratio <= page.maxRatio) return;
// Confirm before alerting: transient states (slow image, animation) rarely repeat.
const confirm = await capture(body);
const confirmed = diffRatio(baseline, confirm);
if (confirmed.ratio <= page.maxRatio) return;
const stamp = new Date().toISOString().replace(/[:.]/g, '-');
await writeFile(`history/${page.id}-${stamp}.png`, confirm);
if (confirmed.diff) await writeFile(`history/${page.id}-${stamp}-diff.png`, confirmed.diff);
await sendSlackAlert({ page, ratio: confirmed.ratio, stamp });
}
await mkdir('baselines', { recursive: true });
await mkdir('history', { recursive: true });
cron.schedule('0 * * * *', async () => {
for (const page of PAGES) {
await checkPage(page).catch((err) => console.error(page.id, err.message));
}
}, { noOverlap: true, timezone: 'UTC' });
A few notes on the comparison:
- pixelmatch's
threshold(default 0.1) is a per-pixel colour distance from 0 to 1, not a percentage of the page. The function returns the number of mismatched pixels. Your ownmaxRatiodecides how many is too many. Set it per page and check it against a few days of captures before you enforce it. - A different hash does not mean a visible change. It only means "run the pixel diff". A matching hash does mean nothing changed.
- A size change counts as a change. On full-page captures, a different page height is often the real signal: a section was added or removed.
- Web fonts are loaded only for full-page captures. Viewport-only captures skip font downloads and render text in fallback fonts. Keep
fullPageconsistent between the baseline and the check.
Step 3: monitor zones, not whole pages
Whole-page diffs on busy pages are noisy. Two ways to narrow them:
Element captures (all plans). Pass a CSS selector and Screenshotly captures only that element. If the element is missing, the request fails with a 400 instead of returning an image. For a pricing table, a missing element is itself worth an alert.
{
"url": "https://www.example.com/pricing",
"device": "desktop",
"selector": "#pricing-table",
"waitForNetworkIdle": true
}
Hide known noise at capture time (Growth). hideSelectors applies display: none to the elements you list before capture: testimonial carousels, "live visitors" counters, cookie banners.
{
"url": "https://www.example.com/",
"device": "mobile",
"fullPage": true,
"waitForNetworkIdle": true,
"hideSelectors": [".testimonial-carousel", "[data-live-counter]", "#cookie-banner"]
}
If you can't change the request, you can blank a fixed region in both images before diffing. Write grey into the same rectangle of each PNG's RGBA data:
function blankRegion(png, { x, y, width, height }) {
for (let row = y; row < Math.min(y + height, png.height); row++) {
for (let col = x; col < Math.min(x + width, png.width); col++) {
const i = (row * png.width + col) * 4;
png.data[i] = png.data[i + 1] = png.data[i + 2] = 128;
png.data[i + 3] = 255;
}
}
}
Step 4: detect text changes with rendered HTML
Pixels tell you that something changed. Text tells you what changed. With "format": "html" (Basic plan or higher), Screenshotly returns the page's HTML after rendering, so text inserted by JavaScript is included. Extract the region you care about and compare the text, for example with cheerio:
import * as cheerio from 'cheerio';
const res = await fetch('https://screenshotly.app/api/screenshot', {
method: 'POST',
headers: { 'x-api-key': process.env.SCREENSHOTLY_API_KEY, 'Content-Type': 'application/json' },
body: JSON.stringify({ url: 'https://www.example.com/terms', format: 'html', waitForNetworkIdle: true }),
});
if (!res.ok) throw new Error(`capture failed: ${res.status}`);
const $ = cheerio.load(await res.text());
const termsText = $('main').text().replace(/\s+/g, ' ').trim();
// Compare termsText with the stored previous version and alert on any difference.
Don't hash the whole HTML document. CSRF tokens, nonces and build IDs change on every request. Compare the extracted text of a specific region.
Step 5: scale out with async jobs and signed webhooks
For a large page set, don't hold dozens of synchronous connections open. Queue the captures and let Screenshotly call you back:
POST /api/jobs/batch(Growth plan or higher) queues up to 20 captures per call.- Each capture can carry a
webhook(Basic plan or higher). When the job finishes, Screenshotly sends ascreenshot.completedorscreenshot.failedevent to your URL. Failed deliveries are retried.
{
"captures": [
{
"url": "https://www.example.com/",
"device": "desktop",
"fullPage": true,
"webhook": { "url": "https://monitor.example.com/hooks/screenshotly", "secret": "YOUR_WEBHOOK_SECRET" }
},
{
"url": "https://www.example.com/pricing",
"device": "desktop",
"selector": "#pricing-table",
"webhook": { "url": "https://monitor.example.com/hooks/screenshotly", "secret": "YOUR_WEBHOOK_SECRET" }
}
]
}
When you set a secret, each delivery carries X-Screenshotly-Signature: sha256=<hex>: an HMAC-SHA256 of the raw request body, keyed with your secret. Verify it before trusting the payload:
import { createHmac, timingSafeEqual } from 'node:crypto';
export function isValidSignature(rawBody, signatureHeader, secret) {
const expected = Buffer.from(`sha256=${createHmac('sha256', secret).update(rawBody).digest('hex')}`);
const received = Buffer.from(signatureHeader ?? '');
return expected.length === received.length && timingSafeEqual(expected, received);
}
The screenshot.completed payload includes data.storageUrl, a signed link to the capture. The link expires (24 hours for webhook links), and the stored asset itself is removed after your workspace's retention period. Download it into your own storage when the webhook arrives. You can also poll GET /api/jobs/{id} until status is SUCCEEDED or FAILED. See the async jobs reference and the webhooks guide.
Step 6: send useful alerts
A Slack incoming webhook accepts Block Kit messages. Include a plain text fallback for notifications:
async function sendSlackAlert({ page, ratio, stamp }) {
const reviewUrl = `https://monitor.example.com/review/${page.id}/${stamp}`;
await fetch(process.env.SLACK_WEBHOOK_URL, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
text: `Visual change on ${page.id}`,
blocks: [
{ type: 'header', text: { type: 'plain_text', text: `Visual change: ${page.id}` } },
{
type: 'section',
fields: [
{ type: 'mrkdwn', text: `*Page:*\n<${page.url}|${page.url}>` },
{ type: 'mrkdwn', text: `*Changed:*\n${(ratio * 100).toFixed(2)}% of pixels` },
],
},
{ type: 'section', text: { type: 'mrkdwn', text: `<${reviewUrl}|Review before / after / diff>` } },
],
}),
});
}
Route severity deliberately. A changed legal page or a missing pricing table may warrant paging someone. A 0.5% shift on the homepage hero probably belongs in a daily digest.
Scheduling options
| Scheduler | Good for | Watch out for |
|---|---|---|
| node-cron on a long-running worker | Frequent checks, local baselines | One process; use noOverlap |
| System cron / Kubernetes CronJob | Running the script as a one-shot job | Baselines must live in shared storage |
GitHub Actions schedule |
Low-frequency checks without a server | Shortest interval is 5 minutes; runs can be delayed or dropped at busy times; runners are ephemeral, so keep baselines in object storage |
| Queue + async jobs | Large page sets | You process webhook deliveries |
A minimal GitHub Actions schedule, running monitor-once.mjs (the checkPage loop above without the cron wrapper):
name: visual-monitor
on:
schedule:
- cron: '17 * * * *' # hourly, off the top of the hour
workflow_dispatch:
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
with:
node-version: 22
- run: npm ci
- run: node monitor-once.mjs
env:
SCREENSHOTLY_API_KEY: ${{ secrets.SCREENSHOTLY_API_KEY }}
SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
Scheduled workflows run on the latest commit of the default branch. At busy times, GitHub may delay or even drop queued scheduled runs; that is why the example runs at minute 17 instead of on the hour. In public repositories, scheduled workflows are disabled after 60 days without repository activity. Check the GitHub Actions documentation for the current rules.
History and retention
Keep the accepted baseline indefinitely, and keep history long enough to answer "when did this change?". A minimal schema:
CREATE TABLE monitored_pages (
id TEXT PRIMARY KEY,
url TEXT NOT NULL,
device TEXT NOT NULL DEFAULT 'desktop',
max_ratio NUMERIC NOT NULL DEFAULT 0.01,
baseline_key TEXT, -- object-storage key of the accepted baseline
baseline_at TIMESTAMPTZ
);
CREATE TABLE page_captures (
id BIGSERIAL PRIMARY KEY,
page_id TEXT NOT NULL REFERENCES monitored_pages(id),
captured_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
object_key TEXT NOT NULL,
sha256 TEXT NOT NULL,
diff_ratio NUMERIC,
alerted BOOLEAN NOT NULL DEFAULT FALSE
);
-- Example policy: keep every capture that triggered an alert, thin the rest after 30 days.
DELETE FROM page_captures
WHERE captured_at < NOW() - INTERVAL '30 days' AND NOT alerted;
Delete the matching objects from storage along with the rows. If captures have to serve as evidence (regulatory, legal or contractual), that is a different requirement with its own rules about integrity and chain of custody. See the website archival guide.
Monitoring pages you don't own
Monitoring third-party pages, such as a partner's status page or a competitor's public pricing, uses the same loop. Before you set it up:
- Read the site's terms of service and respect its
robots.txtand rate limits. Check infrequently. - Some sites block automated browsers. Treat that as the site's answer rather than something to work around.
- Capture only public pages. Don't use other people's credentials or session cookies.
Checklist
- List pages and zones, and give each one an owner and a change budget (
maxRatio). - Work out monthly captures and choose a plan with headroom.
- Capture consistently: same device, same
fullPagesetting, same format. - Hide or blank known-noisy regions, and confirm before alerting.
- Store baselines and history in your own storage, and require a person to approve new baselines.
- Alert with before, after and diff images, and route by severity.
Ready to set up visual monitoring?
Get your free API key →. 100 free captures to build and test the pipeline.
See also:
About the Author

Asad Ali
CTO at ZTABS and the developer behind Screenshotly. Writes about screenshot automation, API design, and building reliable SaaS backends with Next.js, Node.js, and TypeScript.
Credentials: CTO at ZTABS, full-stack developer, builder and maintainer of Screenshotly and its official JavaScript and Python clients
Frequently Asked Questions
How often should I capture a monitored page?
Base it on how quickly you need to know about a change and on your capture budget, not on a default. Work out pages × devices × checks per day × 30 to get monthly captures, then add headroom for confirmation re-captures. Many teams check critical pages hourly and the rest daily, then capture more often for a while after a change is detected.
How do I avoid alert fatigue from rotating testimonials and dynamic banners?
Monitor zones, not whole pages. Capture the parts you care about (pricing table, hero, navigation) as element screenshots with the selector option, and hide known-noisy elements with hideSelectors on the Growth plan. Before alerting, re-capture once to confirm the change, so transient states such as a slow-loading image don't page anyone.
What should the alert contain?
The page and zone that changed, how much changed (mismatched pixels or the text that differs), links to the before, after and diff images, and the time of capture. An alert someone can assess at a glance gets acted on; a bare 'page changed' message gets ignored.
Does Screenshotly schedule checks or store my history?
No. Screenshotly captures a URL when you ask it to. Scheduling (cron, a CI schedule or a queue), storing baselines and history, diffing and alerting all happen in your own code. Assets created with storage or async jobs expire according to your workspace retention setting, so copy anything you need to keep into your own storage.
Ready to capture your first screenshot?
Get started with 100 free screenshots. No credit card required.