changedetection.io

changedetection.io is a lightweight, self‑hosted automation platform that continuously monitors web pages for content changes and delivers real‑time alerts through a rich set of notification channels. From the developer’s perspective, it is essentially a headless browser orchestrator coupled with a change‑diff engine and an extensible webhook API. The core loop is: fetch → normalize → diff → notify, where fetching can be driven by Playwright scripts or simple HTTP requests, normalization is performed via configurable CSS selectors or JSON paths, and diffing leverages a line‑by‑line textual comparison that can be tuned to ignore whitespace or case.

• Language & Runtime: The service is written in Python 3.11, running on the standard CPython interpreter. All logic lives in a single Flask‑based web server that exposes REST endpoints for CRUD operations on watches, step scripts, and notification settings.
• Browser Engine: When the Playwright content fetcher is enabled (default in the paid tier), the application spawns a headless Chromium instance via the official Playwright Python bindings. Browser steps are serialized as a list of actions (click, type, wait) and executed sequentially before the final page snapshot is taken.
• Storage: Watches, step definitions, and notification templates are persisted in a lightweight SQLite3 database for single‑node deployments. For multi‑node or high‑availability setups, the same schema can be migrated to PostgreSQL or MySQL with minimal effort.
• Diff Engine: The diffing logic is built on the standard library’s difflib module, but wrapped to expose granular change metrics (word, line, character). Results are stored as JSON diffs and can be queried via the API for audit or replay purposes.
• Notification Hub: A pluggable dispatcher routes alerts to over 80 destinations (Discord, Slack, Telegram, Email, Webhook, etc.). Each destination is configured via a simple JSON payload and can be extended by adding new dispatcher modules.

• Element‑level Monitoring: Using CSS selectors or XPath, developers can target specific DOM nodes. The visual selector tool (powered by Playwright) lets users graphically pick elements, which are then stored as selector strings.
• Interactive Browser Steps: Prior to change detection, scripts can perform logins, form submissions, cookie acceptance, or any sequence of actions. These steps are stored as a list of Playwright action objects and executed in order.
• Restock & Price Extraction: A built‑in JSON path extractor pulls product price, availability, and metadata from the page’s HTML or embedded scripts. The result can trigger a custom webhook with structured payloads.
• Diff APIs: Endpoints expose raw diffs, summaries, and change statistics. This enables downstream services (e.g., data pipelines) to ingest only the delta rather than full page snapshots.
• Webhook & API Hooks: Every watch change emits a JSON payload to configured webhooks. Developers can chain this into CI/CD pipelines, monitoring dashboards, or custom notification systems.

changedetection.io is designed for simplicity: a single Docker image (ghcr.io/dgtlmoon/changedetection.io) contains the Flask app, SQLite database, and optional Playwright binaries. Containerization is fully supported; environment variables control the database path, notification secrets, and Playwright enablement. For production use:

• Scalability: Spin up multiple containers behind a load balancer. Since state is stored in SQLite, you’ll need shared storage or migrate to PostgreSQL for true multi‑instance concurrency.
• Resource Footprint: A minimal instance requires ~200 MiB RAM; enabling Playwright adds ~1 GiB for Chromium binaries. CPU usage spikes only during step execution, making it suitable for cron‑like polling intervals.
• Self‑Hosting: No external services are required; all dependencies (Python, SQLite, Playwright) run locally. SSL termination is recommended at the reverse proxy layer.

• Plugin System: New notification dispatchers can be added by implementing a simple interface and placing the module in the dispatchers/ directory. The core automatically discovers them on startup.
• API: CRUD endpoints (/api/watches, /api/steps) follow REST conventions and return JSON. Authentication is token‑based; tokens can be rotated via the UI or CLI.
• Webhooks: The payload contains the full diff, a summary, and metadata (URL, timestamp). Developers can filter by change_type or embed additional context.
• Custom Renderers: The visual selector tool can be replaced with a custom UI that writes selectors to the database, allowing integration into proprietary monitoring dashboards.

The application ships with comprehensive documentation (read‑the‑docs style, hosted on GitHub Pages) that covers API usage, step scripting, and advanced configuration. Community support is active on GitHub Issues, Discord, and a public Slack channel. The UI is minimalistic but functional: watch creation, step editing, and notification configuration are all performed through a responsive web interface that communicates with the REST API.

• E‑commerce Price Tracking: Monitor product pages, extract price and stock status, trigger Slack or Discord alerts when a threshold is crossed.
• Content Auditing: Detect policy changes on partner sites, feed diffs into a