MainWP Uptime Kuma Extension

A MainWP extension that automatically keeps an Uptime Kuma (GitHub) instance in sync with your MainWP child sites: every site you manage in MainWP gets its own HTTP (S) monitor, created, updated, and removed automatically as sites are added, changed, or deleted in MainWP. It does not talk to Uptime Kuma directly, it goes through Uptime Kuma API Bridge, a small private REST service that drives Uptime Kuma on the extension's behalf (Uptime Kuma itself has no REST API).

This is an independent, community project. It is not affiliated with, endorsed by, or supported by either the MainWP or the Uptime Kuma projects.

Requirements

• A MainWP Dashboard site with the MainWP plugin installed and active. This extension is installed on the MainWP dashboard, not on the child sites it monitors.
• PHP >= 8.5.
• An Uptime Kuma API Bridge instance already deployed and reachable from the MainWP dashboard, with its bearer token at hand. This extension is useless on its own, it's a client for that bridge.

Installation

1. Download the plugin zip (or clone this repository) and upload it under Plugins > Add New > Upload Plugin on your MainWP dashboard site (or extract it into wp-content/plugins/mainwp-uptime-kuma-extension).
2. Activate it. MainWP will pick it up as an extension: enable it from MainWP > Extensions.
3. Open the extension's settings page from the MainWP extensions list and configure it (see below).

Configuration

The settings page has four tabs:

• Connection: the bridge's base URL (e.g. https://bridge.example.com) and its bearer token. A status label confirms whether the bridge is reachable (GET /health) once both are filled in.
• Target: the Uptime Kuma group every synced site's monitor is created under (pick an existing one or create a new one on the spot), and which Uptime Kuma notifications get attached to newly created monitors.
• Defaults: the check interval, retries, resend interval, and timeout applied to new monitors, plus whether to enable certificate/domain expiry notifications and the cache buster. These are only (re)applied to existing monitors when you explicitly force it from the Sync tab. Day-to-day updates only touch what actually changed (see below).
• Sync: pending/failed job counts, a button to force a full resync of every MainWP site, and a button to requeue jobs that failed after repeated retries.

How it syncs

Each MainWP site becomes one Uptime Kuma monitor:

• Name: the site's hostname (www. stripped).
• Description: the site's name as set in MainWP.
• URL: the site's URL as set in MainWP.
• Group: the group chosen in the Target tab.
• Tags: derived from the site's MainWP groups. A matching Uptime Kuma tag is looked up (or created, using the MainWP group's own color) for each MainWP group the site belongs to.

Sync is event-driven, not polling: adding, editing, or removing a site in MainWP immediately queues a job (mainwp_site_added / mainwp_update_site / mainwp_delete_site), and a WP-Cron task drains that queue every minute (20 jobs per run). MainWP's own periodic "sync all sites" event also triggers a full reconcile pass at most once every 15 minutes, to catch any site change that didn't fire a per-site hook.

To avoid needless API calls, each site's monitor payload is hashed: an update is only sent to the bridge when the hash actually changes (name, description, URL, tags, or group). The interval/retries/timeout defaults are applied when a monitor is first created, and are only reapplied afterwards if you tick "Force reapply defaults to every monitor" on the Sync tab before resyncing, so changing a monitor's check interval by hand in Uptime Kuma isn't silently overwritten by the next sync.

Deleting a site in MainWP deletes its Uptime Kuma monitor. There is currently no way to opt a specific site out of sync other than removing it from MainWP.

Tag colors follow the MainWP group's color at the time a tag is first created. A MainWP group isn't required to have a color set (groups created without one, or programmatically, can have an empty color), in which case its tag just keeps the bridge's default color instead. If you change a group's color afterwards in MainWP, matching Uptime Kuma tags only pick up the new color on the next resync (the "Resync now" button on the Sync tab, or MainWP's own periodic full sync), not immediately, since checking every tag's color on every single site sync would mean an extra bridge call per site for no benefit most of the time.

Troubleshooting

• "The Uptime Kuma bridge is not configured yet." Fill in both the bridge URL and API key on the Connection tab.
• Status shows "Unreachable": the bridge doesn't answer GET /health; check the URL and that the bridge is actually running and reachable from the MainWP dashboard's network.
• Jobs piling up in "Failed": open the Sync tab; failed jobs keep their last error message in the database ({prefix}mainwp_uptime_kuma_queue.last_error) after 5 attempts. Fix the underlying issue (bridge unreachable, invalid group/tag, etc.) and use "Requeue failed jobs".

License

MIT. See LICENSE.