The Heartbeat API in WordPress acts like your website’s pulse: it sends a tiny “I’m alive” ping from your browser to your server every few seconds. This automatic request/response cycle syncs your site’s data, posts, and dashboard, providing real-time updates and crucial functionality for editors, plugins, and admins.
In this glossary article, you’ll learn exactly how the WordPress Heartbeat API works, why it matters, and how to monitor, control, or disable it if it creates high CPU demand on your hosting.
Why the WordPress Heartbeat API Matters?
The Heartbeat API underpins many of WordPress’s most user-friendly features by keeping your browser and server in constant communication. Without it, you would lose convenient auto-saves, collaborative post locks, and live dashboard updates.
- Keeps Your Post Editor Safe: When drafting or editing a post in the WordPress editor, Heartbeat auto-saves your changes every 15–60 seconds, so you never lose work if your browser or connection drops.
- User Locking & Notifications: If two authors try to edit the same post simultaneously, Heartbeat sends notifications (“Your team member is editing this post”) and applies a locking mechanism to prevent content conflicts.
- Real-Time Dashboard Widgets: E-commerce plugins like WooCommerce use the API to update sales data in your dashboard without a full page reload.
- Session Timeout Alerts: Heartbeat can alert you if your login session has expired, prompting you to log in again before you lose unsaved edits.
How Heartbeat API Works: The Basics
Heartbeat operates via small AJAX calls to your server, letting WordPress coordinate data without complete page refreshes. These frequent pings optimize functionality and security by ensuring editors see up-to-date information and that sessions remain valid.
- Browser Sends admin-ajax.php Request: With every Heartbeat tick, your browser sends a tiny AJAX call to /wp-admin/admin-ajax.php.
- Server Processes Request: WordPress runs any hooked functions, retrieves new data, and then sends it back as a JSON response.
- Browser Receives & Acts: Your browser’s JavaScript events catch the response, update the UI (e.g., auto-save, widget refresh), and prepare for the next interval.
js
// Example: Listen for the next heartbeat tick in the frontend
jQuery(document).on(‘heartbeat-tick’, function(event, data) {
console.log(‘Heartbeat response received:’, data);
});
- Default Interval: Editor Screen (15 seconds) and Dashboard & Other Admin Pages (60 seconds).
Core Hooks and Code Examples
Developers leverage Heartbeat’s built-in hooks to add custom features or adjust its behavior. You can tailor the API to exchange the needed data by tapping into these JavaScript and PHP events.
JavaScript Hooks
Below are two primary JS hooks you can tie into for front-end control:
- heartbeat-send: Attach custom data before each request.
- heartbeat-tick: Act on the received data after the request is complete.
js
// Attach extra info on every heartbeat-send event
jQuery(document).on(‘heartbeat-send’, function(e, data) {
data.customValue = jQuery(‘#my-field’).val();
});
PHP Hooks
On the server side, these hooks allow you to modify or react to Heartbeat calls:
- heartbeat_send: Modify the data that the server returns.
- heartbeat_received: Take action when the server receives a tick.
php
add_filter(‘heartbeat_send’, ‘my_heartbeat_send’, 10, 2);
function my_heartbeat_send($response, $screen_id) {
if ($screen_id === ‘post’) {
$response[‘server_time’] = time();
}
return $response;
}
Common Use Cases of WordPress Heartbeat API
Heartbeat’s real-time capabilities power many everyday features in WordPress. Syncing server and browser ensures that dashboards and editors stay current without manual clicks or full reloads.
- Auto-Saving & Revisions: Heartbeat runs seamlessly in the post editor, creating backups every 15 seconds so you can recover lost content.
- Real-Time Sales Data: E-commerce plugin developers use Heartbeat to fetch fresh sales statistics and display them instantly.
- Session Expiration Notices: When your login session nears expiration, Heartbeat shows a notice: “Click here to stay logged in.”
- Collaboration Alerts: You’ll see who’s editing which post on multiauthor sites, preventing overwrite conflicts.
Performance Considerations and High CPU Usage
While indispensable for real-time updates, Heartbeat can become a heavy CPU consumer on busy sites. Each frequent AJAX request to admin-ajax.php uses processing time and memory, which may push shared-hosting accounts over their resource limits.
- Elevated CPU Load: Frequent Heartbeat API calls can significantly increase your server’s CPU usage, especially on shared hosting plans, because each tick requires PHP to process an AJAX request.
- Slower Page Response: As the server handles these requests more, front-end page loads and admin-dashboard interactions may become noticeably slower.
- Risk of Suspension: If the volume of admin-ajax.php requests pushes your site past your host’s CPU limits, your account could be throttled or suspended until usage returns to acceptable levels.
How to Monitor Heartbeat Traffic?
Observing heartbeat activity can help you diagnose performance bottlenecks early. Use server logs and client-side tools to track request frequency and response times.
- Server Logs & Stats: Check CPU usage spikes in cPanel or your hosting dashboard, focusing on /wp-admin/admin-ajax.php entries.
- Browser Dev Tools: In Chrome or Firefox Developer Tools → Network tab → filter “admin-ajax.php” → observe tick frequency and response time.
- Plugin Solutions: Install performance plugins (e.g., Query Monitor) to see Heartbeat calls, memory usage, and execution time directly in the admin dashboard.
Controlling and Limiting the Heartbeat API
If Heartbeat’s default rhythm overwhelms your server, you can slow or disable it selectively. This lets you balance real-time features with optimal performance and resource control.
- Via Plugin: Install Heartbeat Control or use WP Rocket’s built-in settings to adjust intervals or turn off Heartbeat on specific screens.
- Via Code
php
// Reduce Heartbeat frequency to once every 60 seconds
add_filter(‘heartbeat_settings’, function($settings) {
$settings[‘interval’] = 60;
return $settings;
});
// Disable on the front end entirely
add_action(‘init’, function() {
if (!is_admin()) wp_deregister_script(‘heartbeat’);
}, 1);
Risks of Disabling the Heartbeat API
Shutting off Heartbeat may ease CPU strain, but it comes at the cost of several key features. Before you disable it site-wide, understand the trade-offs in user experience and security.
- No Auto-Saves in Classic Editor → manual click on “Save Draft” required for every change.
- Potential data loss if the Internet connection drops during Publish/Update.
- Dashboard widgets and plugins relying on Heartbeat will cease working, reducing real-time reports and features.
Best Practices and Troubleshooting
Rather than kill the Heartbeat entirely, it’s wiser to fine-tune its behavior. By selectively throttling or logging Heartbeat, you preserve its benefits while maintaining server health.
- Throttle, Don’t Kill: Instead of completely disabling it, increase the interval from 15 to 30 or 60 seconds.
- Test in Staging: First, apply interval changes or deregistration in a staging environment to catch issues.
- Combine with Caching: Leverage object or page caching to offset any extra server load from Heartbeat.
- Enable Logging: Hook into heartbeat_received to record ticks and debug unexpected behavior.
Final Thought
The WordPress Heartbeat API keeps your site alive and in sync. It auto-saves drafts, shows real-time data, and prevents editing conflicts. Too many requests can raise CPU use. You can slow it down or disable it where needed. Test changes in a staging site first. With the right balance, Heartbeat boosts functionality without hurting performance.
For more WordPress terms and in-depth explanations, explore the Seahawk Media Glossary.