How to Set Up Webpushr Push Notifications for WordPress

Webpushr is a web push notification platform that delivers real-time browser notifications to opted-in users, even when those users have navigated away from your site entirely. Unlike email or SMS, web push requires no personal contact information — subscribers receive notifications directly through their browser's native notification system via the Web Push Protocol and the Push API.

This guide walks through the complete setup process: from account creation and WordPress plugin configuration to advanced segmentation, trigger-based automation, and subscriber analytics. It also covers technical edge cases — service worker conflicts, HTTPS requirements, iOS compatibility gaps, and performance considerations — that most tutorials skip entirely.

Prerequisites Before You Begin

Before touching the WordPress dashboard, verify that your environment meets the following hard requirements:

• HTTPS is mandatory. The Push API and service workers are restricted to secure origins. A site running on plain HTTP cannot register a service worker and therefore cannot deliver web push notifications. If your site is not yet secured, you need a valid SSL certificate — AlexHost provides SSL Certificates that cover this requirement.
• WordPress 5.0 or higher is recommended for full Gutenberg block editor compatibility with the Webpushr meta box.
• PHP 7.4 or higher on the server side to avoid deprecated function warnings that can silently break plugin initialization.
• Browser support awareness: Chrome, Firefox, and Edge on desktop and Android support the Web Push Protocol. Safari on macOS added support in Safari 16 (macOS Ventura). iOS Safari added limited support in iOS 16.4 for home-screen PWAs only — standard browser-based web push on iOS remains unreliable as of this writing.
• No conflicting service workers. If you already run a PWA plugin or another push notification service, their service workers may conflict with Webpushr's. Audit your active service workers at chrome://serviceworker-internals/ before proceeding.

Step 1: Create and Configure Your Webpushr Account

Navigate to webpushr.com and register a new account. During onboarding, you will be asked for your website's domain. Enter the exact domain as it appears in your browser's address bar, including the www prefix or its absence — this value is used to scope the service worker and mismatches will cause subscription failures.

After registration, Webpushr provisions two critical credentials:

• API Key — used by the WordPress plugin to authenticate REST API calls for sending notifications.
• Auth Token — used for server-side API requests if you later build custom integrations.

Locate both values under Account > API Keys in the Webpushr dashboard and store them securely. The API Key is not a secret in the traditional sense (it is embedded in client-side requests), but the Auth Token must be kept private.

Webpushr Free vs. Paid Plan Limits

For most small WordPress sites, the free tier is sufficient to validate the channel before committing to a paid plan.

Step 2: Install the Webpushr WordPress Plugin

Log in to your WordPress admin panel and follow this path:

1. Go to Plugins > Add New.
2. Search for Webpushr.
3. Locate the official plugin published by Webpushr Inc. — verify the publisher name to avoid installing a similarly named plugin.
4. Click Install Now, then Activate.

Alternatively, install via WP-CLI if you manage WordPress from the command line:

wp plugin install webpushr-web-push-notifications --activate

After activation, a new Webpushr menu item appears in the left-hand WordPress navigation.

What the Plugin Actually Does at the Server Level

Understanding the plugin's architecture helps you troubleshoot issues intelligently. On activation, the plugin:

1. Registers a rewrite rule to serve the service worker file (webpushr-sw.js) from the site root. This is critical — service workers must be served from the root scope to control the entire origin.
2. Injects a JavaScript snippet into every front-end page via wp_enqueue_scripts that loads the Webpushr SDK and registers the service worker.
3. Hooks into publish_post and publish_page WordPress actions to trigger automatic push notifications when content is published.

If your caching plugin aggressively caches the service worker file, subscribers may receive stale push payloads or fail to register entirely. Exclude webpushr-sw.js from your caching rules.

Step 3: Connect the Plugin to Your Webpushr Account

Navigate to Webpushr > Settings in your WordPress dashboard. You will see a field labeled API Key. Paste the API Key you retrieved from the Webpushr dashboard in Step 1.

Click Save Changes. The plugin will make a validation request to the Webpushr API. If the key is valid, a success confirmation appears. If you see an error:

• Confirm there are no leading or trailing whitespace characters in the pasted key.
• Verify your server can make outbound HTTPS requests to api.webpushr.com. Some hardened VPS configurations block outbound connections by default. On a Linux server, test with:

curl -I https://api.webpushr.com

A 200 OK or 301 response confirms connectivity. If the connection times out, check your firewall rules with iptables -L OUTPUT or your hosting provider's network ACL.

If you are running WordPress on a VPS Hosting environment, you have full control over firewall rules and can whitelist the Webpushr API endpoint directly.

Step 4: Configure the Opt-In Prompt

The opt-in prompt is the browser permission dialog that asks users to allow notifications. The browser's native permission dialog cannot be styled — it is rendered by the browser itself. However, Webpushr provides a pre-permission prompt (a custom overlay that appears before the native dialog) which you can fully customize.

Configure the pre-permission prompt in the Webpushr dashboard under Settings > Opt-in Prompt:

• Prompt style: Choose between a bell widget, a top bar, a slide-in box, or a custom modal.
• Prompt text: Write copy that clearly communicates the value of subscribing. Vague prompts like "Allow notifications?" consistently underperform prompts that specify what subscribers will receive, such as "Get notified instantly when we publish new security advisories."
• Prompt delay: Set a delay (in seconds or page views) before showing the prompt. Showing it immediately on page load produces lower opt-in rates than waiting until a user has engaged with at least one piece of content.
• Re-prompt interval: Define how many days must pass before a dismissed user is shown the prompt again. Aggressive re-prompting damages user experience and increases bounce rate.

Opt-In Rate Benchmarks by Prompt Type

Contextual prompts — shown after a user completes a meaningful action like reading an article to the end — consistently outperform all other approaches.

Step 5: Configure Notification Delivery Settings

Automatic Push on Post Publish

In Webpushr > Settings, the Auto-Push Notification toggle controls whether a push notification fires automatically every time you publish a post. When enabled, Webpushr pulls the post title, excerpt, and featured image URL and constructs the notification payload automatically.

Edge case: If you use a staging-to-production workflow where posts are imported or their status is changed programmatically (e.g., via WP-CLI or a migration script), the publish_post hook will fire for every imported post, potentially flooding your subscribers with dozens of notifications in seconds. Disable auto-push before running bulk imports:

wp option update webpushr_auto_push 0

Re-enable it after the import completes.

Manual Push from the Post Editor

For granular control, disable auto-push globally and use the per-post Webpushr meta box in the post editor. This meta box appears below the main content editor and exposes the following controls:

• Send push notification: A checkbox that, when checked, queues a notification on publish or update.
• Custom notification title: Override the post title with a more click-worthy headline for the notification.
• Custom notification message: Override the auto-generated excerpt.
• Custom notification URL: Redirect subscribers to a specific landing page rather than the post permalink — useful for promotional campaigns.
• Custom notification icon: Override the default site icon with a campaign-specific image.

Notification Payload Anatomy

A web push notification payload consists of:

• title — displayed in bold at the top of the notification.
• body — the descriptive text below the title.
• icon — a square image (recommended 192×192 px) shown alongside the notification.
• image — a large banner image shown below the body on supported platforms (Chrome on Android, Chrome on Windows).
• badge — a small monochrome icon shown in the Android status bar.
• url — the destination URL when the user clicks the notification.
• actions — up to two action buttons with custom labels and URLs (supported on Chrome and Edge).

Keeping the title under 50 characters and the body under 120 characters prevents truncation on most platforms.

Step 6: Test Push Notifications End-to-End

Testing in the same browser session where you are logged into WordPress will not give you an accurate picture of the subscriber experience. Use a separate browser profile or an incognito window:

1. Open your website in a private/incognito window.
2. The pre-permission prompt should appear after your configured delay.
3. Click the prompt's call-to-action, then click Allow in the browser's native permission dialog.
4. Return to your WordPress dashboard and publish a test post, or use the Send Test Notification button in the Webpushr dashboard.
5. Verify the notification appears with the correct title, body, icon, and that clicking it navigates to the correct URL.

Common failure modes during testing:

• Notification does not appear: Check that browser notifications are not blocked at the OS level (Windows Focus Assist, macOS Do Not Disturb, Android notification channels).
• Service worker not registering: Open DevTools > Application > Service Workers and confirm webpushr-sw.js is listed as active. If it shows as "waiting," another service worker is blocking activation.
• Icon not loading: The icon URL must be absolute (starting with https://) and the image must be served with permissive CORS headers if hosted on a CDN.

Step 7: Advanced Features — Segmentation, Scheduling, and Triggers

Audience Segmentation

Webpushr's segmentation engine allows you to tag subscribers based on:

• URL-based segments: Automatically tag subscribers who visit specific URLs or URL patterns (e.g., all users who visit /category/security/ are tagged security-readers).
• Custom attributes: Pass arbitrary key-value pairs via the JavaScript SDK to build segments based on user properties your application already tracks.
• Engagement segments: Webpushr automatically tracks last-seen timestamps, allowing you to create re-engagement campaigns targeting subscribers who have not received a notification in 30+ days.

Segmentation requires a paid plan and is configured in the Webpushr dashboard under Segments.

Scheduled Notifications

Scheduling allows you to compose a notification now and deliver it at a future date and time, with timezone support. This is particularly valuable for:

• Time-sensitive promotions with a hard deadline.
• Content published outside of peak traffic hours that you want delivered during high-engagement windows.
• Recurring digest notifications (e.g., weekly roundups).

Custom Trigger-Based Notifications

Custom triggers fire notifications based on JavaScript events on your site. For example, you can fire a notification 24 hours after a user abandons a shopping cart, or when a user reaches a specific scroll depth. Triggers are configured via the Webpushr JavaScript SDK and require custom development work beyond the WordPress plugin's default capabilities.

A/B Testing Notification Copy

On paid plans, Webpushr supports split testing notification titles and body copy across subscriber segments. Run A/B tests to determine which messaging drives higher click-through rates before rolling out a full campaign.

Step 8: Monitor Subscriber Analytics

The Webpushr dashboard provides the following metrics:

• Total subscribers: Active, unsubscribed, and expired endpoint counts.
• Delivery rate: Percentage of sent notifications that were successfully delivered to the browser push service (FCM for Chrome/Edge, Mozilla Autopush for Firefox).
• Click-through rate (CTR): Percentage of delivered notifications that resulted in a click.
• Subscription growth over time: Daily and weekly subscriber acquisition trends.

Important technical note on "delivered" vs. "received": A notification is marked as delivered when the browser's push service (e.g., Google's FCM) accepts the payload. If the user's device is offline, FCM queues the notification and delivers it when the device reconnects — but only within the TTL (Time to Live) window you configure. The default TTL is 28 days. For time-sensitive notifications, set a shorter TTL to avoid delivering stale content.

Platform and Browser Compatibility Matrix

"Full support" means the Web Push Protocol, service workers, and notification actions are all supported. iOS users on standard browser sessions remain outside the reach of web push, which is a meaningful audience gap for mobile-heavy sites.

Hosting Infrastructure Considerations

Web push notification delivery is largely handled by third-party push services (FCM, Mozilla Autopush), so your server's raw throughput is not a bottleneck for delivery. However, your hosting environment does affect:

• Service worker serving speed: The webpushr-sw.js file must be fetched quickly on every page load for browsers to verify the service worker is current. A slow server increases Time to First Byte (TTFB) for this file.
• API response time: When a new post is published, the plugin makes a synchronous API call to Webpushr. On shared hosting with restrictive outbound connection limits, this call can time out and silently fail.
• Webhook reliability: If you configure Webpushr webhooks to notify your server of subscription events, your server must reliably accept inbound POST requests.

Running WordPress on a VPS with cPanel gives you the control to tune PHP execution timeouts, configure outbound firewall rules, and monitor service worker delivery without the restrictions of shared environments. For high-traffic sites where push notification campaigns drive significant concurrent traffic spikes, a Dedicated Server ensures your origin can absorb the resulting click-through load without throttling.

For teams managing multiple WordPress properties, Email Hosting paired with Webpushr creates a two-channel re-engagement strategy — push for immediacy, email for depth.

Technical Decision Matrix: When to Use Webpushr vs. Alternatives

Webpushr's free tier is more limited than OneSignal's, but its service worker implementation is notably cleaner and less prone to conflicts with other WordPress plugins — a practical advantage on complex WordPress installations.

Practical Checklist Before Going Live

• HTTPS is active and the SSL certificate is valid and not self-signed.
• Service worker webpushr-sw.js is accessible at https://yourdomain.com/webpushr-sw.js and returns a 200 status.
• The service worker file is excluded from your caching plugin's cache rules.
• Opt-in prompt delay is set to at least 5 seconds or one page view.
• Auto-push is disabled if you run scheduled bulk imports or content migrations.
• A test notification has been received end-to-end in a clean browser session.
• Notification icon dimensions are 192×192 px and the URL is absolute HTTPS.
• TTL is configured appropriately for your content's time-sensitivity.
• Analytics baseline is recorded before your first campaign so you have a meaningful comparison point.
• GDPR/privacy policy updated to disclose push notification data collection.

FAQ

Does Webpushr work without HTTPS?

No. The Web Push API and service workers are restricted to secure origins by the browser specification. Any site running on HTTP cannot register a service worker and therefore cannot send or receive web push notifications. An SSL certificate is a hard technical requirement, not an optional best practice.

Why are my push notifications not being delivered to some subscribers?

The most common causes are: the subscriber's device was offline beyond the notification's TTL window; the user revoked notification permissions at the browser or OS level; or the browser push service endpoint (FCM, Mozilla Autopush) returned an expired or invalid registration. Webpushr's dashboard marks these as "failed" deliveries and automatically removes endpoints that return a 410 Gone response, which is the correct behavior per the Web Push Protocol specification.

Can I send push notifications to iOS users?

As of iOS 16.4, web push is supported only for Progressive Web Apps (PWAs) that have been added to the home screen. Users browsing your site in Safari or any other iOS browser without adding it to their home screen will not receive web push notifications. This is a platform-level restriction imposed by Apple, not a Webpushr limitation.

Will the Webpushr service worker conflict with my existing PWA or caching plugin?

It can. Only one service worker can control a given scope at a time. If a PWA plugin (e.g., Super PWA) or another push service has already registered a service worker at the root scope, Webpushr's service worker will queue in a "waiting" state and never activate. The resolution is to use a service worker that imports both scripts, or to choose a single push provider and disable the others. Check chrome://serviceworker-internals/ to audit all registered workers on your domain.

Does disabling the Webpushr plugin unsubscribe my existing subscribers?

No. Deactivating the plugin removes the JavaScript SDK from your front end, which prevents new subscriptions and stops automatic notifications. However, existing push endpoint registrations remain valid in the browser until the user explicitly revokes permission or the endpoint expires. If you re-activate the plugin with the same API Key, those subscribers will be reachable again immediately.