Quick Start

Email & Password

Traditional registration with email verification. Passwords must be at least 12 characters with uppercase, lowercase, numbers, and symbols.

Social Login (OAuth)

Sign in quickly with existing accounts:

• Google - Sign in with your Google account
• Apple - Sign in with Apple ID
• GitHub - Sign in with GitHub
• Microsoft - Sign in with Azure account

Admin signup notifications are sent for first-time OAuth registrations as well as email/password registrations.

First-time social signup requires accepting Terms of Service and Privacy Policy from the Sign Up page.

When social sign-in is launched from the monitoring wizard, OAuth opens in a new tab so the wizard stays in place while you authenticate.

Managing Linked Accounts

1. Go to Profile → Linked Accounts
2. Click "Link" to connect a new provider
3. Use "Unlink" to remove (requires at least one auth method)

Note: If you signed up with OAuth only, use "Forgot Password" to set a password.

Visual Mode

Compares screenshots to detect visual changes. Best for:

• Design and layout changes
• Ad placement monitoring
• Image updates
• Styling modifications

Visual alert emails include before/after screenshots with automatic fallback to hosted images if inline attachments are unavailable.

Screenshot artifacts are retained for up to one hour to support reliable asynchronous notification delivery.

Visual element selection captures the selected DOM element instead of a fixed page slice, which reduces false positives from layout shifts. If that element can no longer be found, monitoring pauses automatically and sends an alert email so you can update the selector.

For selector based visual monitors, WebWatchr also stores a normalized DOM baseline for the element subtree and reports DOM level differences (text, attributes, and structure) when the subtree changes.

Text Mode

Compares text content to detect wording changes. Best for:

• Price monitoring
• News and article updates
• Product availability
• Content changes

Document Mode

Downloads documents from direct URLs, extracts text, and diffs against the previous version.

• PDF, DOCX, XLSX, CSV, and TXT support
• Optional PDF page ranges and XLSX sheet selection
• Optional contains and suppress keyword filters
• Best for reports, policy files, and data exports

Comparison Viewer Links

Change notification emails now include a View Comparison link that opens a token-based comparison page with no login required.

• Interactive before and after viewer with a draggable vertical slider divider
• Works across visual, text, document, and AI monitoring modes
• AI comparisons include confidence, reasoning, and in-page feedback controls
• Text comparisons show inline highlighted diffs with complete page context so changes are visible in place
• Visual and AI modes include a text changes panel with word level diffs when text extraction is available
• Visual comparisons include GitHub-style overlays: red on the before image for removed or changed pixels, and green on the after image for added or changed pixels

Supported Formats

• PDF
• DOCX
• XLSX
• CSV
• TXT

How It Works

1. Enter a document URL (auto-detected by file extension)
2. Extract normalized text from file contents
3. Compare with the previous extracted version
4. Send notification when configured diff conditions match

Configuration Options

• Document URL (required)
• Document Type (auto-detect or explicit type)
• Page Range (PDF)
• Sheet Name (XLSX)
• Contains and suppress text filters

API Reference

• POST /jobs/create with monitoringMode: "text" and a documentUrl field
• GET /jobs/document-versions/:jobId
• GET /jobs/document-versions/:jobId/diff/:versionId

Tier Limits

• Starter and Trial: latest change only
• Pro: up to 10 changes per job, retained for 180 days
• Premium: up to 100 changes per job, retained for 365 days

How to Access

1. Open Dashboard and select History
2. Choose a job to open its timeline
3. Expand a row to view before, after, and diff images

Downgrade Behavior

If your tier changes to Starter or Trial, previous history remains retained by policy and you can regain full timeline access after upgrading again.

Columns

• New - Unprocessed changes
• Reviewed - Changes you acknowledged
• Dismissed - Changes you want to ignore

Auto-populate

Every time a monitor detects and notifies you of a change, it appears as a new card on the Review Board automatically.

Drag and drop

Drag cards between columns to change their status. Drag and drop is available on desktop.

Card details

Each card shows the monitor name, monitoring mode (Visual, Text, Document, or AI), percent changed, and when the change was detected. Click a card to open the full comparison view.

Bulk actions

Use Mark all reviewed and Dismiss all to process multiple items at once.

How It Works

When a page changes, AI Mode evaluates whether the change is relevant to your intent. If it is, you get notified with quoted evidence showing exactly what changed. Irrelevant changes are silently ignored.

Writing a Good Intent

Be specific about what you want to track. The more precise your intent, the fewer false alerts you will receive.

• Good: "Alert when price drops below $50"
• Good: "Alert when tickets become available"
• Good: "Alert when new Senior Engineer roles appear"
• Avoid: "Alert on changes"

Evidence and Dedup

AI notifications include quoted evidence from the detected change. Duplicate notifications are automatically suppressed to reduce noise.

Credit Usage

AI Mode consumes 1 credit per check.

Best Practices

AI Mode analyzes text content extracted from the page or selected element. It does not detect visual changes such as layout shifts, image swaps, or color changes. Keep this in mind when configuring your monitoring job.

• Use element selection to focus on relevant page sections and reduce noise
• Write specific intents that describe a concrete condition, not a vague topic
• Use longer intervals (30 to 60 min) to conserve credits
• Test your intent with the preview feature before enabling the job
• Avoid intents about visual appearance, images, or page layout since these are not tracked in AI mode
• Combine element selection with a focused intent for the most accurate results

Credit Pools and Packs

• Subscription credits reset each billing period.
• Purchased credits from one-time packs never expire.
• Checks consume subscription credits first, then purchased credits.
• Maximum credit balance per account is 30,000 credits.

Dashboard Chat

• Open AI Helper from the chat button on the dashboard.
• Ask for threshold, interval, and monitoring mode recommendations.
• Apply bot suggestions directly from action buttons in the chat panel.

Email Suggestions

• When noisy patterns are detected, AI Helper includes a tip in the change email.
• Use Apply Now to apply the recommendation with one click.
• Use Dismiss to suppress similar suggestions.

Tier Access

• Trial / Starter: threshold-based email suggestions
• Growth / Pro / Premium: chat assistant + AI-analyzed email suggestions
• Chat usage limits reset daily based on your subscription tier.

Enabling SEO Monitoring

1. Create a new job or open an existing job in Edit mode
2. Turn on SEO Tracking in Job Settings
3. Save changes to begin collecting SEO snapshots on each run

Tracked Fields

SEO Change Notifications

SEO alerts include field-level diffs with a severity label:

• Critical - Canonical, robots, and title changes that can materially affect indexing
• High - Meta description and Open Graph tag updates
• Medium - H1, Twitter, and structured data changes
• Low - Link, image alt, and performance metadata adjustments

API Endpoints

• GET /jobs/:jobId/seo/latest - Current SEO snapshot
• GET /jobs/:jobId/seo/history - Full SEO change history
• GET /jobs/:jobId/seo/timeline - Field timeline for title, meta description, and canonical

Schedule Type

Choose how your job runs:

• Continuous - Checks at a fixed interval (5 min to 1 week)
• Specific Hours - Only runs during selected days and hours with timezone support

Use the schedule picker to select business hours, weekends, or custom time windows. Timezone selection includes search so you can quickly find your region. You can edit the schedule type and configuration from the job edit panel.

Weekday selections in Specific Hours execute reliably on the exact days you choose.

Shorter intervals require a paid plan.

Threshold

• Any Change - Triggers on any pixel change
• Small Change - Very sensitive to minor differences
• Medium Change - Moderate sensitivity (recommended)
• Large Change - Only significant changes

Wait Time

Delay before capturing: 0, 3, or 6 seconds. Use longer times for slow-loading pages.

Disable JavaScript

Load pages without JS execution. Useful for static content or faster loading.

SEO Tracking Toggle

Enable SEO Tracking to store metadata snapshots and field-level history for title, meta description, canonical URL, robots, Open Graph tags, H1 headings, and structured data.

Requirements

• Paid subscription (Starter or higher)
• Proxy feature enabled for your account

Connection Types

• Server IP (Default) - Uses the WebWatchr server IP directly.
• Managed Proxy - Uses a proxy from the WebWatchr-managed pool.
• Custom Proxy URL - Bring your own proxy (BYOP).

BYOP URL Format

Use http://username:password@host:port or socks5://host:port.

Country Selection

When using Managed Proxy, you can select a country to route requests through a proxy in that region. Choose "Auto" to let the system pick any available proxy. Country selection is available both as an account default (Settings) and per-job (Wizard).

Default vs Per-Job

Settings proxy defaults apply to all jobs unless a job-level proxy override is set in the wizard.

Security

Custom proxy URLs are encrypted at rest. Proxy URLs targeting private networks, internal services, or reserved IP addresses are rejected. Only HTTP, HTTPS, and SOCKS5 proxy schemes are accepted. You are responsible for the privacy and security practices of any third-party proxy provider you configure.

Restricted Countries

Proxies located in countries under US OFAC sanctions or classified as high-risk are not supported. Custom proxy URLs are geo-checked when saved and at runtime. Managed proxy country selections are validated against the restricted list. Affected countries include Cuba, Iran, North Korea, Syria, Russia, Belarus, Myanmar, Afghanistan, Venezuela, Somalia, South Sudan, Yemen, Libya, and Zimbabwe.

Creating a Team

Open Dashboard -> Profile -> Teams, click Create Team, and enter a name.

Inviting Members

Open a team, go to Members, click Invite Member, enter an email, then choose a role.

Roles Explained

• Owner - Full control including delete team and ownership transfer.
• Admin - Manage members, invitations, and alert rules.
• Member - Create and share monitors, add tags, and post comments.
• Viewer - Read-only access to shared monitors and comments.

Sharing Monitors

In Team detail -> Monitors, click Share Monitor and select monitors from your Job, Uptime, Cron, or Topic lists.

Tagging Monitors

Add tags directly on shared monitors using the + control. Common tags include pricing and production.

Alert Rules

In Alert Rules, create rules using: IF tag matches THEN notify selected team members.

Severity Thresholds

Each member can have a threshold of all, high, or critical to control which team alerts they receive.

Comments

Open a shared monitor detail panel to read or add comments and one-level replies with role-based permissions.

Activity Feed

The Activity tab records invitations, role changes, monitor sharing, tags, rules, and comment events in chronological order.

Tier Requirement

Team Collaboration is available on Growth, Pro, and Premium plans. Trial and Starter accounts can see the Team area but must upgrade to use it.

Getting XPath from Browser

1. Right-click element → Inspect
2. In DevTools, right-click HTML → Copy → Copy XPath

Visual Selector

1. Click the visual selector button when creating an action
2. Clickable elements will be highlighted
3. Click the element you want to target
4. XPath is automatically generated

Testing XPath

Open browser console (F12) and run:

$x("//your-xpath-here")

If it returns the element, your XPath works.

Common Patterns

• //button[@id='submit'] - By ID
• //a[contains(text(), 'Login')] - By text
• //input[@type='email'] - By attribute
• //*[contains(@class, 'btn')] - By partial class
• //div[@data-testid='header'] - By data attribute

Tips

• Use stable attributes like id or data-*
• Avoid dynamic IDs that change on each load
• Test in browser console before using

How to Import

1. Go to Dashboard → Import Jobs
2. Upload a JSON file or paste JSON
3. Review the preview
4. Click Import

JSON Format

{
  "jobs": [
    {
      "joburl": "https://example.com",
	      "monitoringmode": "visual",
	      "schedule_config": {
	        "type": "interval",
	        "intervalMinutes": 30
	      },
	      "actions": {
	        "interval": 30,
        "threshold": 0.1,
        "waitFor": 3,
        "disableJS": false,
        "actions": []
      }
    }
  ]
}

With Actions

{
  "jobs": [
    {
      "jobURL": "https://example.com/page",
      "monitoringMode": "text",
      "actions": {
        "interval": 60,
        "threshold": 0,
        "waitFor": 3,
        "actions": [
          { "type": "click", "xpath": "//button[@id='load']" },
          { "type": "wait", "duration": 3 },
          { "type": "delete", "xpath": "//div[@class='popup']" }
        ]
      }
    }
  ]
}

Field Reference

Required fields:

• joburl - URL to monitor (http/https). jobURL is also accepted.
• monitoringmode - "visual", "text", "document", or "ai". monitoringMode is also accepted.
• schedule_config.intervalMinutes - Check frequency in minutes: 5, 10, 15, 30, 60, 120, 180, 360, 720, 1440, 10080
• actions.threshold - Change sensitivity: 0, 0.05, 0.1, 0.2
• actions.waitFor - Wait before capture: 0, 3, 6 seconds

Optional fields:

• actions.disableJS - Disable JavaScript (boolean)
• actions.actions - Pre-capture actions array
• actions.interval - Legacy compatibility input for import files
• aiintent - Required for AI mode: what to watch for (max 200 chars). aiIntent is also accepted.
• entirePage - Text mode only: monitor full page (boolean)
• textselector / elementselector - Element selector (CSS/XPath) for text or AI mode, or "box" for region selection
• textfiltercontains / textFilterContains and textfilterexcludes / textFilterExcludes - Keyword filters for text/document monitoring
• text_similarity_threshold / textSimilarityThreshold - Text mode: similarity threshold 0.85-0.99 (default 0.95)

Imported active jobs start running automatically after creation.

AI monitors reuse cached irrelevant diff decisions and resolved Smart Action selectors when available to reduce repeated token usage.

AI Mode Example

Basic AI monitoring with intent:

{
  "jobs": [
    {
      "joburl": "https://example.com/schedule",
      "monitoringmode": "ai",
      "aiintent": "Alert when John OR Mary works evening shift",
      "actions": {
        "interval": 60,
        "threshold": 0,
        "waitFor": 3
      }
    }
  ]
}

Limits

• Max file size: 1MB
• Max jobs per import: 100
• Max actions per job: 12

Authentication

Send your key in the Authorization header for every request.

Authorization: Bearer ww_live_xxxxxxxxxxxxxxxxx
Content-Type: application/json

Base URL: https://webwatchr.io

API Keys

Create and manage API keys from your Dashboard > Developers tab.

• Keys are prefixed with ww_live_ (production) or ww_test_ (testing)
• Assign scopes to limit access: jobs:read, jobs:write, cron:read, cron:write, uptime:read, uptime:write, or * for full access
• Keys are hashed on creation and cannot be retrieved later. Store them securely.
• Revoke compromised keys immediately from the Developers tab

Rate Limits

API requests are rate limited per IP address to prevent abuse.

When rate limited, the API returns 429 Too Many Requests. Standard rate limit headers (RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset) are included in all responses.

Endpoints

• POST /jobs/create - Create job (jobs:write)
• GET /jobs/get-jobs - List jobs (jobs:read)
• PATCH /jobs/update-job - Update job (jobs:write)
• DELETE /jobs/delete-job - Delete job (jobs:write)
• GET /jobs/export-jobs?jobIds=id1,id2 - Export selected jobs
• POST /jobs/import-jobs - Import jobs
• GET /jobs/document-versions/:jobId - List document versions for a monitor
• GET /jobs/document-versions/:jobId/diff/:versionId - Get a specific document version diff
• GET /jobs/:jobId/seo/latest - Get the latest SEO snapshot
• GET /jobs/:jobId/seo/history - Get SEO change history for a monitor
• GET /jobs/:jobId/seo/timeline - Get title, meta description, and canonical timeline entries

Create Job Request

{
  "jobUrl": "https://example.com/pricing",
  "monitoringMode": "ai",
  "interval": 15,
  "changeThreshold": 0.05,
  "scheduleConfig": {
    "type": "interval",
    "intervalMinutes": 15
  },
  "aiIntent": "Notify when pricing changes",
  "textSelector": "//main",
  "textContent": "Optional seed text",
  "textSimilarityThreshold": 0.95,
  "nickname": "Pricing watch"
}

Allowed values:

• monitoringMode: visual, text, document, ai
• interval: 5, 10, 15, 30, 60, 120, 180, 360, 720, 1440, 10080
• changeThreshold: 0, 0.05, 0.1, 0.2
• textSimilarityThreshold: 0.85 to 0.99
• aiIntent is required when monitoringMode is ai
• documentUrl triggers document extraction (auto-detected by URL extension, or set explicitly with any monitoring mode)
• documentType, documentPageRange, and documentSheetName are optional document fields
• jobURL, url, and snake_case aliases are also accepted

Create Job cURL

curl -X POST https://webwatchr.io/jobs/create \
  -H "Authorization: Bearer ww_live_xxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "jobUrl":"https://example.com/pricing",
            "monitoringMode":"ai",
	    "interval":15,
	    "changeThreshold":0.05,
	    "aiIntent":"Notify when pricing changes"
	  }'

List Jobs cURL

Optional query params: limit and offset. Defaults are limit=50 and offset=0. limit is capped at 200.

curl "https://webwatchr.io/jobs/get-jobs?limit=50&offset=0" \
  -H "Authorization: Bearer ww_live_xxxxxxxxxxxxxxxxx"

Update Job Request

{
  "jobid": "8f79e0e5-0f7d-4ec7-bfdf-3e0f21c89a2e",
  "nickname": "Pricing watch (hourly)",
  "status": "active",
  "threshold": 0.1,
  "schedule_config": {
    "type": "interval",
    "intervalMinutes": 60
  },
  "aiintent": "Notify when enterprise pricing changes"
}

Common update fields: nickname, status, threshold, schedule_config, aiintent, webhook_url, webhook_enabled.

Update Job cURL

curl -X PATCH https://webwatchr.io/jobs/update-job \
  -H "Authorization: Bearer ww_live_xxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "jobid":"8f79e0e5-0f7d-4ec7-bfdf-3e0f21c89a2e",
    "threshold":0.1,
    "status":"paused"
  }'

Delete Job Request

{
  "jobid": "8f79e0e5-0f7d-4ec7-bfdf-3e0f21c89a2e"
}

Delete Job cURL

curl -X DELETE https://webwatchr.io/jobs/delete-job \
  -H "Authorization: Bearer ww_live_xxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"jobid":"8f79e0e5-0f7d-4ec7-bfdf-3e0f21c89a2e"}'

AI Health Monitoring

Admin monitoring includes hourly AI health reports that correlate infrastructure and runtime signals to detect silently broken services.

• Runs independently from Temporal on an hourly host cron
• Combines Docker status, service health checks, database metrics, Temporal state, and Redis telemetry
• Stores reports with severity, findings, and metrics snapshots for historical review
• Sends immediate critical alerts to admins through Pushover

Webhooks

Receive HTTP notifications when changes are detected. Configure a webhook URL in your job settings and WebWatchr will POST event data whenever a change is detected.

• Configure webhook URLs in job settings
• HMAC signature verification for security
• View delivery history and test webhooks from the job details panel

Event Types

Payload

{
  "event": "job.change_detected",
  "job_id": "abc123",
  "url": "https://example.com/page",
  "nickname": "My Monitored Page",
  "timestamp": "2025-01-24T12:00:00Z",
  "change": {
    "type": "visual",
    "difference_percentage": 5.2
  }
}

Delivery and Retries

WebWatchr expects a 2xx response within 10 seconds. Failed deliveries are retried up to 5 times with exponential backoff:

• Retry 1: after 30 seconds
• Retry 2: after 2 minutes
• Retry 3: after 8 minutes
• Retry 4: after 30 minutes
• Retry 5: after 2 hours

After all retries are exhausted, a failure notification email is sent to the job owner. View delivery history and error details from the job details panel in your dashboard.

Signature Verification

Verify the X-Webhook-Signature header to confirm requests come from WebWatchr:

const crypto = require('crypto');

const signature = req.headers['x-webhook-signature'];
const expected = crypto
  .createHmac('sha256', webhookSecret)
  .update(JSON.stringify(req.body))
  .digest('hex');

if (signature === expected) {
  // Valid request
}

Notification Channels

WebWatchr can send change alerts to additional platforms beyond email. Configure channels in Profile -> Notifications, then enable them per job.

Supported channels:

• Discord - Open Server Settings -> Integrations -> Webhooks, create a new webhook, choose the target channel, and copy the URL
• Slack - Create an app at api.slack.com/apps (From Scratch), enable Incoming Webhooks under Features, click Add New Webhook to Workspace, select a channel, and copy the URL
• Microsoft Teams - Right-click the target channel, select Workflows, choose "Post to a channel when a webhook request is received", and copy the generated URL

Each channel can be tested before enabling. Delivery results for each configured channel are tracked alongside email delivery.

• Channel routing is available for both page jobs and topic monitors
• Topic monitors in new_info_only mode send weekly heartbeat updates when checks run without new findings
• Topic monitor create/edit dialogs include query testing, helper guidance, and a thoroughness selector
• Dashboard now includes cross-monitor recent activity and latest finding previews on collapsed topic cards
• Topic knowledge state is capped to the latest 100 facts to keep intelligence prompts focused
• Topic monitors now run on per-monitor Temporal schedules instead of shared batch polling

Smart Notifications

Notification settings are configured per monitor, giving you fine-grained control over each topic watchr independently.

Minimum Importance Score

Filters notifications when a finding confidence score falls below a threshold you set (0 to 100%). Findings that do not meet the threshold are recorded but do not trigger an alert.

Quiet Hours

Suppresses notification delivery during a specified window of UTC hours. Findings detected during quiet hours are held and delivered once the window ends.

Configuring These Settings

Both settings are available in the create and edit dialogs for each topic monitor. There is no global notification preferences page; all configuration lives on the individual monitor.

Cron Monitoring

Monitor scheduled tasks with ping-based heartbeats.

• Create monitors in Dashboard → Developer → Cron Jobs
• Send HTTP pings from your cron jobs
• Get alerts when jobs miss their schedule
• View analytics: success rate, duration percentiles, uptime

# Simple ping (job completed)
curl https://webwatchr.io/jobs/ping/{ping_key}

# Start ping (job started)
curl https://webwatchr.io/jobs/ping/{ping_key}/start

# Complete ping (job completed successfully)
curl https://webwatchr.io/jobs/ping/{ping_key}/complete

# Fail ping (job failed)
curl https://webwatchr.io/jobs/ping/{ping_key}/fail

# With duration and exit code
curl "https://webwatchr.io/jobs/ping/{ping_key}/complete?duration=1500&exitCode=0"

Uptime Monitoring

Monitor website availability with HTTP checks and custom assertions.

• HTTP/HTTPS endpoint monitoring
• Configurable check intervals (1-60 minutes)
• Response time tracking and SLA reports
• Automatic incident detection and resolution

Assertions:

• status_code - Validate specific HTTP status codes
• latency_lt_ms - Response must be under X milliseconds
• json_path - Validate JSON response values
• header_present - Check for required response headers
• body_contains - Response must include specific text

{
  "url": "https://api.example.com/health",
  "assertions": [
    { "type": "status_code", "value": 200 },
    { "type": "latency_lt_ms", "value": 500 },
    { "type": "json_path", "path": "$.db", "value": "ok" },
    { "type": "body_not_contains", "value": "maintenance" }
  ]
}

Scheduling Reliability

Monitoring jobs include automatic reliability controls to ensure consistent execution.

• Automatic retries for transient failures
• Isolated workloads so issues in one area do not affect others
• Self-healing reconciliation to correct schedule drift
• Graceful handling during deployments to minimize missed checks
• Notification delivery is tracked per channel for visibility

Quick Start

# Install
npm install -g @webwatchr/cli

# Login (get API key from Dashboard → Developer → API Keys)
webwatchr login

Auto-detect Cron Jobs

Automatically scan your crontab and set up monitoring:

# Create monitors matching your cron job names
cat > webwatchr.yaml << 'EOF'
cron_monitors:
  - name: Daily Backup
    schedule: "0 2 * * *"
    grace_period: 300
EOF

# Sync monitors to WebWatchr
webwatchr sync webwatchr.yaml

# Auto-install ping commands into your crontab
webwatchr cron install --dry-run  # Preview
webwatchr cron install            # Apply

YAML Configuration

monitors:
  - name: API Health Check
    url: https://api.example.com/health
    interval: 60
    timeout: 5000
    assertions:
      - type: status_code
        value: 200
      - type: latency_lt_ms
        value: 500
    auth:
      type: bearer
      token_env: API_TOKEN  # Uses $API_TOKEN

cron_monitors:
  - name: Daily Backup Job
    schedule: "0 2 * * *"
    grace_period: 300

Commands

# Validate config
webwatchr validate monitors.yaml

# Sync to WebWatchr
webwatchr sync monitors.yaml --dry-run  # Preview
webwatchr sync monitors.yaml            # Apply
webwatchr sync monitors.yaml --prune    # Remove unlisted

# View status
webwatchr status
webwatchr status --type uptime
webwatchr status --type cron
webwatchr status --json

CI/CD Integration

name: Sync Monitors

on:
  push:
    branches: [main]
    paths: ['monitors.yaml']

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g @webwatchr/cli
      - run: webwatchr validate monitors.yaml
      - run: webwatchr sync monitors.yaml
        env:
          WEBWATCHR_API_KEY: ${{ secrets.WEBWATCHR_API_KEY }}

Webhook Subscriptions

Create endpoint subscriptions that receive typed events such aschange.detected, change.resolved, job.failed, job.recovered,uptime.down, uptime.up, cron.failed, and cron.recovered.

1. Go to Dashboard -> Integrations -> Webhooks
2. Click Create Subscription
3. Enter a destination HTTPS URL
4. Select the events to deliver
5. Optionally add a secret and JSON filters

Payload format

{
  "event": "change.detected",
  "timestamp": "2026-02-28T19:00:00.000Z",
  "data": {
    "job_id": "abc123",
    "job_name": "Pricing Page",
    "url": "https://example.com/pricing"
  }
}

Signature verification

When a secret is configured, requests include an HMAC SHA-256 signature inX-WebWatchr-Signature plus metadata headers:X-WebWatchr-Event, X-WebWatchr-Delivery-Id, and X-WebWatchr-Timestamp.

const crypto = require('crypto');

const signature = req.headers['x-webwatchr-signature'];
const expected = crypto
  .createHmac('sha256', process.env.WEBWATCHR_SECRET)
  .update(JSON.stringify(req.body))
  .digest('hex');

if (signature !== expected) {
  return res.status(401).send('Invalid signature');
}

Subscriptions auto-disable after repeated failed deliveries. Re-enable or update endpoint settings in the same tab.

RSS Feeds

RSS feeds publish account activity for readers like Feedly, Slack RSS apps, and internal dashboards.

• All events - Jobs, uptime, and cron in one feed
• Job changes - Change detection events only
• Uptime incidents - Down and recovery updates
• Cron alerts - Late, failed, and recovered cron events

Each feed provides both RSS and Atom URLs. Copy either URL and subscribe in your reader.

Zapier and Make Quick Start

Zapier

1. Create a new Zap with Webhooks by Zapier as trigger
2. Choose Catch Hook and copy the generated URL
3. Paste that URL in your WebWatchr webhook subscription
4. Send a test event and map payload fields in the next Zap step

Make

1. Create a scenario with a Custom Webhook module
2. Copy the webhook URL from Make
3. Create a matching WebWatchr subscription and send a test
4. Build downstream actions from the parsed payload fields

Supported Platforms

• Slack - OAuth workspace connection and channel picker
• Discord - OAuth server connection and text channel routing
• Teams - OAuth team connection with team and channel selection
• Telegram - Link-code flow through the WebWatchr bot

How to Connect

1. Open Dashboard -> Profile -> Integrations
2. Click Add Integration and choose your platform
3. Complete OAuth authorization or Telegram link-code verification
4. Use Manage Channels to pick the destination channel
5. Enable that notification channel on each monitor where you want delivery

OAuth vs Manual Webhooks

• OAuth integrations provide channel discovery, centralized reconnect, and integration status tracking
• Manual webhooks stay available in Profile -> Notifications for custom endpoints and advanced routing
• Both approaches can be mixed within the same account

Per-Monitor Routing

Notification channels are attached to monitors individually. You can route one monitor to a private incident room and another monitor to a public status channel.

Integration Limits by Tier

• Trial: 1 integration
• Starter: 2 integrations
• Pro: 5 integrations
• Premium: 10 integrations

Troubleshooting

• Token expired: Reconnect or refresh the integration from Profile -> Integrations
• Bot removed: Re-install the app/bot in the workspace and reconnect
• No channels listed: Verify workspace permissions and required scopes

CLI Tests

Validate your YAML configuration before syncing:

webwatchr validate monitors.yaml

Testing Webhooks

Use the test button in job settings to send a sample webhook payload to your endpoint and verify it arrives correctly.

Job Not Running

• Check job is active (not paused)
• Verify URL is accessible
• Check for JavaScript errors if disableJS is false

No Changes Detected

• Lower threshold for higher sensitivity
• Increase wait time for slow-loading pages
• Use visual mode for layout changes

XPath Not Working

• Test in browser console with $x()
• Check for dynamic IDs that change
• Use data-* attributes or text content instead

Actions Failing

• Add Wait action before interactions
• Verify element exists when action runs
• Check XPath targets the correct element

Need Help?

Contact us for support.