​
What a Heartbeat Does

A heartbeat is the integration payload that carries WordPress-side health and environment data to Watchman Tower. It is used for:
  • validating the initial connection
  • syncing settings such as interval and pause state
  • sending internal WordPress telemetry into Watchman Tower

​
Current Heartbeat Model

The current plugin is not centered around a browser-driven JavaScript loop. Instead, the important paths are:
  • an immediate heartbeat on first connection
  • an immediate heartbeat after settings are saved
  • a WT-triggered REST endpoint for controlled heartbeat execution

​
High-Level Flow

​
Outgoing Heartbeats

Outgoing heartbeat delivery is handled by the plugin backend. The heartbeat payload is built in PHP and posted to the Watchman Tower metric endpoint. During early connection it can use token-based auth; after pairing it uses the stored HMAC secret and site ID.

​
Triggers You Can Rely On

  • connect: sent immediately after a token is saved during pairing
  • settings: sent immediately after settings are saved
  • manual/internal reasons: available in backend code paths when needed

​
WT-Triggered Endpoint

The plugin registers this route: 
/wp-json/wt/v1/heartbeat
That route:
  • accepts POST requests
  • verifies X-WT-Key, X-WT-Timestamp, and X-WT-Signature
  • checks the stored pairing state
  • runs the heartbeat job only when the request is valid
If the plugin is paused, the route returns a paused response instead of executing the heartbeat job.

​
Payload Delivery Notes

The plugin sends JSON to the configured heartbeat endpoint with headers that can include:
  • Authorization: Bearer ... during early pairing
  • X-WT-Key
  • X-WT-Timestamp
  • X-WT-Signature

​
Error State

If heartbeat delivery fails, the plugin records the latest error in wthb_options.last_error. If heartbeat delivery succeeds, the plugin records the success timestamp in wthb_options.last_success. You can inspect both values with: 
wp option get wthb_options --format=json

​
What This Means Operationally

The WordPress plugin should be understood as an internal signal source inside the broader Watchman Tower workflow, not as a standalone scheduler dashboard. For that reason, the most important controls are:
  • connection state
  • interval
  • pause
  • unlink

​
Next Steps