alert-website-change/README.md

Website Change Alert

A Python tool that monitors websites for content changes and sends email notifications.

Features

• ✅ Monitor any website URL
• ✅ Hash-based change detection
• ✅ Optional XPath or CSS selector support to monitor specific page sections
• ✅ Email notifications via SMTP
• ✅ Environment-based configuration
• ✅ Designed for cron scheduling

Setup

1. Install dependencies:

   poetry install
   

2. Configure environment:

   cp .env.example .env
   # Edit .env with your settings
   

3. Run manually to test:

   poetry run python alert.py
   

Configuration

Edit .env with your settings:

Required Settings

• URL: The website to monitor
• SMTP_HOST: SMTP server hostname (e.g., smtp.gmail.com)
• SMTP_USER: Your SMTP username
• SMTP_PASSWORD: Your SMTP password or app-specific password
• FROM_EMAIL: Sender email address
• TO_EMAIL: Recipient email address

Optional Settings

• SELECTOR: XPath or CSS selector to monitor specific content (leave empty for full page)
• SELECTOR_TYPE: Type of selector - xpath (default) or css
• CACHE_FILE: Location to store hash cache (default: .cache/hash.txt)
• SMTP_PORT: SMTP port (default: 587)
• SMTP_USE_TLS: Use TLS encryption (default: true)

Usage Examples

Monitor entire page:

URL=https://example.com/news
SELECTOR=

Monitor specific section with XPath:

URL=https://example.com/news
SELECTOR=//div[@class='main-content']
SELECTOR_TYPE=xpath

Monitor specific section with CSS selector:

URL=https://example.com/news
SELECTOR=.main-content
SELECTOR_TYPE=css

Scheduling with Cron

Add to your crontab (crontab -e):

# Check every hour
0 * * * * cd /path/to/alert-website-change && /path/to/poetry run python alert.py

# Check every 15 minutes
*/15 * * * * cd /path/to/alert-website-change && /path/to/poetry run python alert.py

# Check daily at 9 AM
0 9 * * * cd /path/to/alert-website-change && /path/to/poetry run python alert.py

To get the full path to poetry:

which poetry

Email Provider Setup

Gmail

1. Enable 2-factor authentication
2. Generate an app-specific password: https://myaccount.google.com/apppasswords
3. Use the app password in SMTP_PASSWORD

Other Providers

Common SMTP settings:

• Gmail: smtp.gmail.com:587 (TLS)
• Outlook: smtp-mail.outlook.com:587 (TLS)
• Yahoo: smtp.mail.yahoo.com:587 (TLS)

How It Works

1. First run: Fetches the page, computes a hash, and saves it to cache
2. Subsequent runs:
   • Fetches the page content
   • Computes hash of current content
   • Compares with cached hash
   • If different: sends email and updates cache
   • If same: exits silently

Troubleshooting

Import errors during development

Run poetry install to install all dependencies.

No email received

• Check spam folder
• Verify SMTP credentials
• Test with a simple manual run
• Check cron logs: grep CRON /var/log/syslog (Linux) or log show --predicate 'process == "cron"' --last 1h (macOS)

XPath/CSS selector returns nothing

• Test your selector in browser DevTools
• Use //text() at the end of XPath to get text content
• Verify the selector matches elements on the page