Technical documentation for GrowthWebMonitor — a self-hosted uptime, performance and image-weight monitor for the websites your agency manages. This page covers how the plugin works, setup, the shortcode, checks and alerts, settings, data model, REST API, and the AI / MCP abilities layer.

Version: 1.0.0  |  Requires: WordPress with WP-Cron enabled; Abilities API (WordPress 6.9+) for the AI layer  |  Text domain: growthwebmonitor

1. Overview — how it works

GrowthWebMonitor turns one WordPress installation into a monitoring hub for many sites. Each monitored site is stored as a private custom post (gp_website), and three scheduled jobs check them in the background:

  • Uptime ping — an HTTP request to each site. The ping is the source of truth for the UP/DOWN status.
  • Performance — Google PageSpeed Insights scores for desktop and mobile.
  • Heavy images — scans the images on each site’s page and records any that exceed your size limit or return an HTTP error.

It is single-tenant: all sites belong to the installation, settings are global, and one API token connects external integrations. The plugin exposes three interfaces on top of the same data:

  • Front-end dashboard — the [growthwebmonitor] shortcode (dashboard + site management).
  • REST API — the growthwebmonitor/v1 namespace, authenticated with a global token.
  • AI abilities — WordPress Abilities API tools, optionally exposed over MCP.

2. Installation & setup

  1. Upload and activate the plugin. On activation it creates three tables (see section 7), stores default settings and schedules the background jobs.
  2. Go to GrowthWebMonitor → Settings in wp-admin and enter your Google PageSpeed API key. Without it, performance checks are skipped (pings and image scans still run).
  3. Review alert recipients, thresholds and check frequencies (section 5).
  4. Create a page with the [growthwebmonitor] shortcode — or use the button in Settings that creates the dashboard page for you.
  5. Add your sites from the dashboard’s Sites tab (or from the GrowthWebMonitor menu in wp-admin).

Tip: WP-Cron only runs when the site receives traffic. For reliable minute-level checks on a low-traffic install, disable WP-Cron’s page-load trigger and call wp-cron.php from a real server cron job.

3. Shortcode

[growthwebmonitor]

Renders the monitoring app with two tabs:

  • Dashboard — aggregated metrics and a table of every site with its current status, scores and last check.
  • Sites — add, edit and delete monitored sites.

Clicking a site opens an inline detail panel with performance charts over time, failed pings grouped by day, and the list of heavy images. From there you can run Ping now or a Full check (PageSpeed + ping + images) on demand.

Access: the shortcode only renders for users with the manage_options capability; everyone else sees a “no permission” notice. To give non-admin staff access, grant manage_options to their role with a role-editor plugin.

Charts are rendered with ApexCharts, loaded from the jsDelivr CDN.

4. Checks & alerts

CheckCron hookDefault frequencyWhat it doesAlert
Uptime pinggp_cron_hourlyHourlyHTTP GET to each site (30 s timeout). 200 and 403 count as UP; anything else, including timeouts, counts as a failure. Only failures are stored, to keep the table small.Email when a site accumulates 3 consecutive failures.
Performancegp_cron_dailyDailyRuns PageSpeed Insights v5 for desktop and mobile (retrying once on failure) and stores both scores.Email listing sites whose desktop or mobile score falls below its threshold.
Heavy imagesgp_cron_daily_imagesDailyFetches the site’s page, collects every <img src>, and checks each file’s size.No email; results appear in the site detail panel, the API and the abilities.

Frequencies are configurable per check:

  • Ping: every 15 min, 30 min, hour, 6 hours, twice daily, or daily.
  • Performance: hourly, every 6 hours, twice daily, daily, or weekly.
  • Images: daily, weekly, or monthly.

Changing a frequency reschedules the job automatically. Deactivating the plugin unschedules all three jobs.

5. Settings

All settings live in GrowthWebMonitor → Settings (requires manage_options) and are stored as WordPress options:

SettingOptionDefault
Google PageSpeed API keygp_pagespeed_api_key(empty)
Alert email recipientsgp_alert_emailsSite admin email
Email notifications on/offgp_notifications_enabledOn
Desktop score threshold (0–100)gp_threshold_desktop75
Mobile score threshold (0–100)gp_threshold_mobile75
Max image size (KB)gp_max_image_size_kb512
Ping / PageSpeed / image frequencygp_freq_ping, gp_freq_pagespeed, gp_freq_imageshourly / daily / daily

The Settings screen is also where you generate or revoke the API token (section 6). To run checks immediately instead of waiting for the schedule, use Ping now / Full check in a site’s detail panel, or the check-all-sites ability (section 8).

6. REST API

Namespace: growthwebmonitor/v1  —  base URL /wp-json/growthwebmonitor/v1.

Authentication: a single global token, generated in Settings. Only a SHA-256 hash is stored, so copy the token when it is shown. Send it in any of these ways:

  • Authorization: Bearer <token> header (recommended)
  • X-API-Token: <token> header
  • ?token=<token> query parameter

Missing or invalid tokens return 401. All endpoints are read-only (GET).

RouteDescription
/sitesAll sites with their current status and last check.
/sites/performance?num=10Latest N PageSpeed logs for every site.
/sites/{id}/performance?num=30PageSpeed logs for one site.
/sites/pingLive ping to every site (status, HTTP code, response time in ms).
/sites/{id}/pingLive ping to one site.
/sites/getpings?days=7Failed-ping history for every site (last 30 entries if days is omitted).
/sites/{id}/getpings?days=7Failed-ping history for one site.

Example

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://example.com/wp-json/growthwebmonitor/v1/sites

Typical uses: a status page, a Slack bot, or a central agency dashboard that aggregates several installs.

7. Data model

Each site is a gp_website post (private, not publicly queryable). Its URL and latest results are post meta: url, status (UP/DOWN), last_check, performance_desktop, performance_mobile.

History is stored in three custom tables (with the site’s table prefix):

TableColumnsNotes
{prefix}gp_logsid, time, website_id, status, performance_desktop, performance_mobileOne row per PageSpeed run.
{prefix}gp_pingsid, time, website_id, statusFailed pings only (HTTP code, or 400 for connection errors).
{prefix}gp_large_imagesid, time, website_id, image_url, image_size, status_codeImages over the size limit or returning an error.

8. AI abilities & MCP

GrowthWebMonitor registers 15 abilities on the WordPress Abilities API (WordPress 6.9+), in three categories. On older WordPress versions this layer is simply skipped.

AbilityCategoryType
growthwebmonitor/get-sitesSitesread-only
growthwebmonitor/get-siteSitesread-only
growthwebmonitor/add-siteSiteswrite
growthwebmonitor/update-siteSitesidempotent
growthwebmonitor/delete-siteSitesdestructive
growthwebmonitor/ping-siteCheckswrite (live ping, updates status)
growthwebmonitor/check-siteCheckswrite (PageSpeed + ping + images; up to ~60 s)
growthwebmonitor/check-all-sitesCheckswrite (full check on every site; slow)
growthwebmonitor/get-dashboard-summaryDiagnosticsread-only
growthwebmonitor/get-sites-downDiagnosticsread-only
growthwebmonitor/get-sites-below-thresholdDiagnosticsread-only
growthwebmonitor/get-sites-with-heavy-imagesDiagnosticsread-only
growthwebmonitor/get-site-performanceDiagnosticsread-only
growthwebmonitor/get-site-pingsDiagnosticsread-only
growthwebmonitor/get-site-imagesDiagnosticsread-only

Each ability declares a JSON input/output schema, so an assistant can safely handle requests such as “which client sites are down right now?” or “list sites with a mobile score under 50”.

Permissions & MCP visibility

  • Every ability requires manage_options by default.
  • Non-destructive abilities are MCP-public by default. delete-site is destructive, so it is not exposed over MCP unless you opt in.
  • The required capability and MCP visibility of each ability (or a whole category) can be overridden from the plugin’s Abilities settings, stored in the gwm_abilities_config option. Per-ability overrides take precedence over category defaults, which take precedence over the code defaults.

9. FAQ & troubleshooting

Performance scores stay at 0.

Check that a Google PageSpeed API key is saved in Settings. Without a key the performance check is skipped. The PageSpeed API can also time out on very slow sites; the plugin retries once per run.

Checks don’t run on schedule.

WP-Cron needs traffic to fire. On quiet installs, trigger wp-cron.php from a server cron job, or run a site’s check on demand from its detail panel.

Why does a 403 count as UP?

Many sites behind a firewall or bot protection return 403 to automated requests while working normally for visitors. Treating it as UP avoids false “site down” alerts.

Can non-admin staff use the dashboard?

The shortcode, settings and abilities require manage_options. Grant that capability to the staff role, or change the ability capabilities in the Abilities settings.

The REST API returns 401.

Generate a token in Settings and send it as a Bearer token. If the token was revoked or regenerated, update your integration with the new one.


Back to GrowthWebMonitor product page.

Scroll to Top