Creating custom apps for WordPress

Watchful allows developers to extend its monitoring capabilities through custom apps integrated into existing WordPress plugins.

Using the Watchful\App\Alert interface and the watchful_app_alerts filter, your plugin can generate informational or error alerts that Watchful collects during site validation.

This guide demonstrates how to build a custom app that monitors a WordPress option and generates an alert when its value changes.

For an introduction to the custom-app system, see Creating custom apps.

Before you begin

You will need:

• A WordPress site connected to Watchful.
• An installed and active Watchful client.
• An existing WordPress plugin that you can modify.
• Familiarity with PHP and WordPress hooks.

You do not need to install a separate example app or create a standalone Watchful plugin. Your custom app becomes part of your existing plugin.

Step 1: Register the Watchful integration

The following example monitors a status value stored in the WordPress options table.

When the status changes, the plugin generates an informational alert.

Add the following code to your plugin’s bootstrap file:

add_action('plugins_loaded', static function () {
    if (!interface_exists('Watchful\\App\\Alert')) {
        return;
    }

    require_once __DIR__ . '/includes/class-watchful-alert.php';

    add_filter('watchful_app_alerts', static function ($alerts) {
        $current = wp_json_encode([
            'status' => (string) get_option('acme_monitor_status', 'healthy'),
        ]);
        if (!is_string($current)) {
            return $alerts;
        }

        $previous = get_option('acme_watchful_baseline', null);
        if ($previous === null) {
            add_option('acme_watchful_baseline', $current, '', false);
            return $alerts; // First collection establishes a silent baseline.
        }

        if ($previous !== $current) {
            $alerts[] = new Acme_Watchful_Alert(
                'Acme monitor status changed to: ' .
                (string) get_option('acme_monitor_status', 'healthy')
            );
            update_option('acme_watchful_baseline', $current);
        }

        return $alerts;
    });
});

This code:

1. Waits until WordPress has loaded its plugins.
2. Confirms that the Watchful alert interface is available.
3. Loads your custom alert class.
4. Registers a callback for collecting alerts.
5. Compares the current status with its previously recorded value.
6. Generates an alert when the status changes.

The first collection establishes a baseline without generating an alert.

Replace Acme and the acme_ option names with identifiers unique to your plugin.

Checking for the Watchful interface ensures that your plugin continues operating normally when the Watchful client is absent or inactive.

Step 2: Create the alert class

In includes/class-watchful-alert.php add the following code:

<?php
defined('ABSPATH') || exit;

final class Acme_Watchful_Alert implements \Watchful\App\Alert
{
    private $message;

    public function __construct($message)
    {
        $this->message = (string) $message;
    }

    public function getMessage() { return $this->message; }
    public function getLevel() { return self::LEVEL_INFO; }
    public function getParameter1() { return null; }
    public function getParameter2() { return null; }
    public function getParameter3() { return null; }
}

The class implements the five methods required by the Watchful alert interface.

Alert messages

The getMessage() method returns the message Watchful will process.

Use a complete, descriptive message that clearly identifies the event.

For example:

Acme monitor status changed to: degraded

Alert severity

The getLevel() method determines the alert severity.

Use self::LEVEL_INFO for informational alerts:

public function getLevel()
{
    return self::LEVEL_INFO;
}

Use self::LEVEL_ERROR for errors:

public function getLevel()
{
    return self::LEVEL_ERROR;
}

Watchful supports these two documented severity levels. There is no separate warning level.

Optional parameters

The getParameter1(), getParameter2(), and getParameter3() methods provide additional strings associated with the alert.

Return null when a parameter is not needed.

All five methods must be implemented.

Step 3: Test your custom app

After adding the code:

1. Activate your plugin on a WordPress site connected to Watchful.
2. Refresh data for the site in Watchful to establish the initial baseline.
3. Change the value stored in acme_monitor_status.
4. Refresh data for the site again.
5. Check Watchful for the resulting custom-plugin event.

For example, changing the stored status from healthy to degraded generates the message:

Acme monitor status changed to: degraded

Running another validation without changing the status should not generate another alert.

You can adapt the example to monitor any application-specific condition available to your plugin.

Reporting events that occur between validations

The example above compares the current state with a stored baseline.

This works well when monitoring settings or conditions whose current value is important.

However, an event that occurs and disappears between Watchful validations may not be detected.

For example, a temporary API failure could begin and end before Watchful collects information from the site.

To report such events reliably, record them when they occur using your plugin’s normal WordPress hooks or callbacks.

Then expose those recorded events through watchful_app_alerts during a subsequent Watchful validation.

Because the alert contract does not provide delivery acknowledgements, your plugin must define how events are retained, identified, and replayed.

WordPress development requirements

When developing a production integration:

• Implement all five methods of Watchful\App\Alert.
• Append alert objects to the collection rather than associative arrays.
• Always return the incoming $alerts collection, preserving alerts from other integrations.
• Confirm the Watchful interface exists before loading a class that implements it.
• Include the standard ABSPATH guard in your plugin’s entry file and supporting PHP files.
• Use unique class names and option names.
• Handle unexpected values without interrupting WordPress or Watchful.

The Watchful client calls the alert object’s getter methods directly, so implementing the interface correctly is essential.

Configuring notifications

Watchful collects your custom app alerts during site validation and processes them through its existing notification system.

Generating an alert does not guarantee that an email or other notification will be delivered.

Review your notification preferences in Watchful and enable the appropriate notifications for informational and error events.

For a broader explanation of alert collection and notification behavior, see Creating custom apps.

Summary

WordPress custom apps let your existing plugins contribute application-specific monitoring information to Watchful.

By implementing the Watchful\App\Alert interface and registering the watchful_app_alerts filter, you can generate alerts without building a separate monitoring or notification service.