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/v1namespace, authenticated with a global token. - AI abilities — WordPress Abilities API tools, optionally exposed over MCP.
2. Installation & setup
- Upload and activate the plugin. On activation it creates three tables (see section 7), stores default settings and schedules the background jobs.
- 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).
- Review alert recipients, thresholds and check frequencies (section 5).
- Create a page with the
[growthwebmonitor]shortcode — or use the button in Settings that creates the dashboard page for you. - 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
| Check | Cron hook | Default frequency | What it does | Alert |
|---|---|---|---|---|
| Uptime ping | gp_cron_hourly | Hourly | HTTP 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. |
| Performance | gp_cron_daily | Daily | Runs 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 images | gp_cron_daily_images | Daily | Fetches 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:
| Setting | Option | Default |
|---|---|---|
| Google PageSpeed API key | gp_pagespeed_api_key | (empty) |
| Alert email recipients | gp_alert_emails | Site admin email |
| Email notifications on/off | gp_notifications_enabled | On |
| Desktop score threshold (0–100) | gp_threshold_desktop | 75 |
| Mobile score threshold (0–100) | gp_threshold_mobile | 75 |
| Max image size (KB) | gp_max_image_size_kb | 512 |
| Ping / PageSpeed / image frequency | gp_freq_ping, gp_freq_pagespeed, gp_freq_images | hourly / 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).
| Route | Description |
|---|---|
/sites | All sites with their current status and last check. |
/sites/performance?num=10 | Latest N PageSpeed logs for every site. |
/sites/{id}/performance?num=30 | PageSpeed logs for one site. |
/sites/ping | Live ping to every site (status, HTTP code, response time in ms). |
/sites/{id}/ping | Live ping to one site. |
/sites/getpings?days=7 | Failed-ping history for every site (last 30 entries if days is omitted). |
/sites/{id}/getpings?days=7 | Failed-ping history for one site. |
Example
curl -H "Authorization: Bearer YOUR_TOKEN" \
https://example.com/wp-json/growthwebmonitor/v1/sitesTypical 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):
| Table | Columns | Notes |
|---|---|---|
{prefix}gp_logs | id, time, website_id, status, performance_desktop, performance_mobile | One row per PageSpeed run. |
{prefix}gp_pings | id, time, website_id, status | Failed pings only (HTTP code, or 400 for connection errors). |
{prefix}gp_large_images | id, time, website_id, image_url, image_size, status_code | Images 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.
| Ability | Category | Type |
|---|---|---|
growthwebmonitor/get-sites | Sites | read-only |
growthwebmonitor/get-site | Sites | read-only |
growthwebmonitor/add-site | Sites | write |
growthwebmonitor/update-site | Sites | idempotent |
growthwebmonitor/delete-site | Sites | destructive |
growthwebmonitor/ping-site | Checks | write (live ping, updates status) |
growthwebmonitor/check-site | Checks | write (PageSpeed + ping + images; up to ~60 s) |
growthwebmonitor/check-all-sites | Checks | write (full check on every site; slow) |
growthwebmonitor/get-dashboard-summary | Diagnostics | read-only |
growthwebmonitor/get-sites-down | Diagnostics | read-only |
growthwebmonitor/get-sites-below-threshold | Diagnostics | read-only |
growthwebmonitor/get-sites-with-heavy-images | Diagnostics | read-only |
growthwebmonitor/get-site-performance | Diagnostics | read-only |
growthwebmonitor/get-site-pings | Diagnostics | read-only |
growthwebmonitor/get-site-images | Diagnostics | read-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_optionsby default. - Non-destructive abilities are MCP-public by default.
delete-siteis 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_configoption. 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.