README

Vigilant WordPress Healthchecks

A WordPress plugin that provides a healthcheck endpoint for any site and integrates seamlessly with Vigilant.

Features

Secure REST endpoint (/wp-json/vigilant/v1/health) protected by a bearer token.
Built-in scheduler heartbeat that verifies WP-Cron is running and reports failures back to Vigilant.
Extensible registry so you can add your own checks or metrics alongside the built-in catalogue.

Configuration

API token

Navigate to Settings → Vigilant Healthchecks and paste the token generated by Vigilant or use your own if you do not use Vigilant.
Every request to the health endpoint must send Authorization: Bearer <token>.

Checks and metrics

The settings page lists all available checks and metrics; toggle anything you do not need.
Disabled checks are never instantiated, reducing overhead on constrained installs.

Scheduler heartbeat

The plugin registers vigilant_healthchecks_cron_monitor, which is scheduled every minute.
When WP-Cron runs, the last heartbeat timestamp is stored and surfaced through the Cron check.
Adjust the allowed delay via the vigilant_healthchecks_cron_threshold filter (default 5 minutes).
If you disable WP-Cron, ensure a system cron invokes wp cron event run --due-now so the monitor continues to run.

Usage

REST endpoint

The health payload is exposed via the WordPress REST API:

POST /wp-json/vigilant/v1/health

Example request:

curl -X POST "https://example.com/wp-json/vigilant/v1/health" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"

A 401 Unauthorized response indicates the token has not been configured or is invalid.

Registering custom checks and metrics

Hook into vigilant_healthchecks_prepare to register additional checks or metrics before the payload is assembled:

use Vigilant\HealthChecksBase\Checks\Metric;
use Vigilant\WordpressHealthchecks\HealthCheckRegistry;

add_action('vigilant_healthchecks_prepare', function (HealthCheckRegistry $registry): void {
    $registry->registerCheck(MyCustomCheck::make());
    $registry->registerMetric(MyCustomMetric::make());
});

Custom checks must extend Vigilant\HealthChecksBase\Checks\Check, while metrics extend Vigilant\HealthChecksBase\Checks\Metric.

Check availability

Each check self-reports whether it can run (for example, the Redis check requires the PHP Redis extension). Inapplicable checks are skipped automatically so they do not produce noise in Vigilant.

Available Checks

Check	Description
DatabaseCheck	Verifies the WordPress database connection and executes a simple query.
SiteHealthCheck	Surfaces critical issues reported by WordPress Site Health.
CoreVersionCheck	Compares the installed core version against the latest release.
RedisCheck	Connects to the Redis instance defined by `WP_REDIS_*` constants and performs a `PING`.
PluginUpdatesCheck	Counts plugins with pending updates via `wp_update_plugins`.
CronCheck	Confirms WP-Cron has run within the configured threshold.

Available Metrics

Metric	Description
MemoryUsageMetric	Reports current system memory usage percentage.
DiskUsageMetric	Reports disk utilisation percentage.
CpuLoadMetric	Emits the 1-minute CPU load average.
DatabaseSizeMetric	Measures the total size of WordPress tables in megabytes (cached by default for 5 minutes).

Events & Filters

vigilant_healthchecks_prepare - add or remove checks and metrics programmatically.
vigilant_healthchecks_cron_threshold - override the maximum seconds between cron heartbeats.
vigilant_healthchecks_database_size_cache_ttl - change the TTL (seconds) for cached database size calculations.
vigilant_healthchecks_force_core_update_check / vigilant_healthchecks_force_plugin_update_check - force WordPress to refresh update metadata before running the respective checks.

Development Environment

A ready-to-use Docker setup lives in devenv/.

Ensure Docker is running.

Start the stack:

docker compose -f devenv/docker-compose.yml up --build

Visit http://localhost:8000 (WordPress admin: admin / secret).

The plugin is mounted from your working copy and activated automatically; configure the token from the settings page and test the endpoint locally:

curl -X POST "http://localhost:8000/wp-json/vigilant/v1/health" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"

Quality

Install dependencies and run the existing toolchain:

composer install
./vendor/bin/phpunit
./vendor/bin/phpstan analyse

vigilant / healthchecks

Maintainers

Details