Creating custom apps

Watchful supports custom apps that extend its monitoring capabilities beyond standard CMS features. By integrating Watchful with your own plugins and extensions, you can monitor application-specific conditions, detect changes, and generate alerts that are processed through Watchful.

For example, you might create a custom app to monitor a third-party integration, detect changes to important configuration settings, or report errors generated by your own software.

Custom apps run within your existing CMS installation and use the Watchful client to report information during site validation. There is no need to build a separate notification service or communicate directly with the Watchful API.

Custom apps are supported through platform-specific integrations for WordPress and Joomla!.

How custom apps work

Custom apps use Watchful’s existing site validation process to collect and report information.

The process works as follows:

1. Your plugin or extension detects a condition or records an event locally.
2. During site validation, the Watchful client collects alerts generated by your custom app.
3. The client includes those alerts in its authenticated response.
4. Watchful processes the information as custom-plugin events.
5. Events are recorded and processed according to Watchful’s notification settings.

Alerts are collected when Watchful validates a site. They are not sent immediately when the underlying event occurs.

For example, suppose your extension detects that an external service has become unavailable. Your extension can record that condition and expose an alert during the next Watchful validation.

If the service recovers before the next validation, a temporary condition might go undetected unless your extension preserves a record of the event.

For this reason, custom apps should store events locally when those events need to be reported reliably.

Understanding alerts

Custom apps use a simple alert structure consisting of a message, severity level, and optional parameters.

Field	Description
message	A nonempty, user-readable message describing the event.
level	An integer indicating severity: 1 for information or 2 for error.
parameter1	Optional string containing additional information.
parameter2	Optional string containing additional information.
parameter3	Optional string containing additional information.

Watchful recognizes two alert levels:

• 1 — Informational alert, processed as plugin_sends_info.
• 2 — Error alert, processed as plugin_sends_error.

Use only these two documented levels.

The alert contract does not support a separate warning level, custom event types, arbitrary data objects, or delivery acknowledgements.

Messages should be clear and specific, and include the optional parameters specified by the app.

Configuring notifications

Creating an alert does not automatically mean an email or other notification will be delivered.

Watchful processes custom-app events through its existing notification system. Notification delivery depends on the applicable notification settings and successful event processing.

Review your notification preferences in Watchful and enable the relevant notifications according to your monitoring needs.

This allows custom apps to participate in your existing monitoring workflow without requiring a separate notification mechanism.

See Install and configure Watchful Apps for more details on using apps and configuring notifications.

Best practices

When developing custom apps:

1. Use descriptive alert messages that explain the condition being reported.
2. Generate alerts only for meaningful changes or events.
3. Establish an initial baseline when monitoring changes in application state.
4. Preserve short-lived events locally when they need to survive until the next validation.
5. Handle errors and missing dependencies without interrupting your CMS.
6. Keep collected information compact and consistent.
7. Test both changed and unchanged conditions.
8. Enable the relevant notifications in Watchful.

Getting started

The implementation of a custom app depends on your CMS.

WordPress

WordPress custom apps use the Watchful\App\Alert interface and the watchful_app_alerts filter.

The app can generate alerts based on information already available to your plugin.

See Creating custom apps for WordPress for implementation instructions and code examples.

Joomla!

Joomla! custom apps use adapter plugins belonging to the watchfulliApps plugin group.

These adapters communicate application-specific information to the Watchful component during site validation.

See Creating custom apps for Joomla! for implementation instructions and code examples.