Getting Started

Search for WPSignal in the WordPress plugin directory (Plugins → Add New), or download the ZIP from wordpress.org/plugins/wpsignal.

1. Upload and activate the plugin in Plugins → Add New → Upload
2. Navigate to Settings → WPSignal

On the WPSignal settings page you will find a Connect to WPSignal button. Enter your WPSignal API key from the dashboard and click the button.

The plugin registers your site with the WPSignal server and automatically saves the generated site_key, publish_secret, and jwt_secret to your wp_options table. No manual configuration needed.

Go to WPSignal → Kitchen Sink in the WordPress admin menu. This page shows five panels:

• › Connection Status — live WebSocket state indicator
• › Registered Triggers — table of all active triggers
• › Live Event Log — realtime stream of received events
• › Publish Form — manually send a test event
• › Token Inspector — decode and inspect your current JWT

If the connection status shows Connected, your setup is working. Use the Publish Form to send a test event and watch it appear in the Event Log instantly.

The plugin automatically enqueues client.js for logged-in users. The script connects via WebSocket (SSE fallback) and dispatches a native CustomEvent for each received event.

Listen for events with plain JavaScript:

document.addEventListener('wpsignal:post.updated', (e) => {
    console.log('Post updated:', e.detail);
    // e.detail = { event: 'post.updated', data: { post_id, ... }, channel: '...' }
});

The event name format is wpsignal:{event_name}. The built-in trigger fires wpsignal:post.updated whenever a post is saved.

Save any post in the WordPress editor and observe the event fire in your browser console.

Use the fluent WPSignal::trigger() builder to publish on any WordPress action hook. Register triggers on the wpsignal_loaded action (or later on init).

add_action('wpsignal_loaded', function () {
    WPSignal::trigger('comment.created')
        ->on('wp_insert_comment', 10, 2)
        ->channel('events')
        ->data(function ($comment_id, $comment) {
            return [
                'comment_id' => $comment_id,
                'post_id'    => $comment->comment_post_ID,
                'author'     => $comment->comment_author,
            ];
        })
        ->when(function ($comment_id, $comment) {
            return (int) $comment->comment_approved === 1;
        })
        ->register();
});

add_action('wpsignal_loaded', function () {
    WPSignal::trigger('order.status_changed')
        ->on('woocommerce_order_status_changed', 10, 3)
        ->channel('events')
        ->data(function ($order_id, $old_status, $new_status) {
            return [
                'order_id'   => $order_id,
                'old_status' => $old_status,
                'new_status' => $new_status,
            ];
        })
        ->register();
});

For one-off publishes outside of a hook, call WPSignal::publish() directly:

// Publish from anywhere in your plugin or theme
WPSignal::publish('events', 'custom.event', [
    'message' => 'Hello from PHP',
    'time'    => time(),
]);

This sends an HMAC-signed HTTP POST to the WPSignal server immediately.