Troubleshoot web push
Find out why a web push notification didn't arrive, what each web push failure reason means, and how people can turn notifications back on after they block them.
Check the delivery first
A successful subscription, or a successful identify call, doesn’t mean that a notification arrived. When a notification doesn’t show up, start with its delivery in Customer.io:
- Open the automation or broadcast and go to the Sent tab. You can also find the delivery in the person’s activity.
- Find the delivery for your test person and check its status. Expand the row to see its failure reason, if it has one.
| What you see | What it means |
|---|---|
| No delivery at all | The person doesn’t have a web device. They haven’t subscribed, they signed out (which removes the browser from their profile), or their browser unsubscribed. Check the Devices tab on their profile. |
| Sent, but not Delivered | Customer.io handed the notification to the browser’s push service, but the browser hasn’t shown it yet. The browser might be closed or offline. The push service holds the notification for one day by default, or until your broadcast’s send deadline, and delivers it if the browser comes back online before then. See browser support. |
| Delivered, but you didn’t see anything | The service worker showed the notification, but the operating system might have hidden it. Check the computer’s or phone’s notification settings and Focus or Do Not Disturb settings. |
| Opened | Someone clicked the notification or one of its buttons. |
| Suppressed, Bounced, or Failed | Customer.io didn’t send the notification, or the push service refused it. Check the failure reason. |
Failure reasons
| Failure reason | What it means | What to do |
|---|---|---|
WEBPUSH_RENDER_FAILED | The Notification icon, Badge, Action buttons, Replace earlier notification with the same tag, Show time (event time instead of arrival), or App badge count (Safari / Home Screen apps) use a Liquid variable that doesn’t exist for this person or event, so Customer.io didn’t send the notification. Customer.io retries the delivery in case the data arrives, and the delivery fails if it still doesn’t render. A missing variable in the title, message, or another field that app push also uses fails the delivery with a Liquid error instead. | Add the missing data to your event or person, or use the default filter (latest Liquid) or an if/else fallback (legacy Liquid). See personalize with Liquid. |
WEBPUSH_UNREGISTERED | The browser isn’t subscribed anymore. The person turned off notifications, cleared their site data, or the subscription expired. Customer.io removes the device from the person’s profile. | Nothing. The person needs to subscribe again to get web push. |
WEBPUSH_CUSTOM_PAYLOAD_UNSUPPORTED | The message uses the Custom Payload editor. Customer.io only sends Rich Push messages to browsers. | Rebuild the message with the Rich Push editor. |
WEBPUSH_PAYLOAD_TOO_LARGE | The rendered notification is bigger than browsers allow. | Shorten your text, URLs, or custom data. Remember that Liquid can make fields longer than they look in the composer. |
WEBPUSH_INVALID_REQUEST | The push service refused the notification. | Try sending again. If it keeps happening, contact support. |
WEBPUSH_VAPID_AUTH_FAILED | The push service refused your workspace’s web push credentials. Customer.io retries the delivery. | Check that VAPID subject in Settings > Push > Web uses a real, public domain you control. Apple rejects subjects like mailto:alerts@example.. Fix the subject and click Save; don’t regenerate your keys. |
WEBPUSH_VAPID_REJECTED | The browser subscribed with a different public key than your workspace uses now, usually because someone regenerated the keys. | The person needs to subscribe again. Make sure your website uses the current public key from Settings > Push > Web. |
WEBPUSH_INVALID_SUBSCRIPTION or WEBPUSH_MISSING_KEYS | The web device on the person’s profile is missing information that Customer.io needs to send to it. | Make sure you add web devices with our web push plugin. The person needs to subscribe again. |
WEBPUSH_RETRYABLE | The push service was busy or unavailable. Customer.io retries the delivery. | Nothing. |
NoProviderConfigured | Web push isn’t set up for this workspace. | Generate your web push keys. |
Notifications are blocked
When someone blocks notifications for your site, the browser stops asking, and your website can’t change that. In Safari and Firefox, closing the permission prompt without choosing (for example, by pressing Escape) also blocks notifications, and your site can’t tell the difference.
When Notification.permission is denied, show people how to allow notifications for your site in their browser, then ask them to click your button again.
| Browser | How to allow notifications again |
|---|---|
| Chrome and Edge | Click the site controls icon to the left of the address, open the site’s settings or permissions, and set Notifications to Allow. Labels vary by version. |
| Firefox | Click the crossed-out bell or the permissions icon to the left of the address, and remove the Send notifications: Blocked permission. Then click your button again and choose Allow. You can also go to Settings > Privacy & Security > Permissions > Notifications. |
| Safari on macOS | Go to Safari > Settings > Websites > Notifications and set your site to Allow, or remove it so that Safari asks again. If notifications are allowed but don’t appear, check System Settings > Notifications and Focus. |
| Safari on iOS and iPadOS | Go to Settings > Notifications, choose your Home Screen app, and turn on Allow Notifications. Then open the app from the Home Screen. |
Other common problems
The button doesn’t show a permission prompt
- Safari: Make sure your click handler calls
webPush.subscribe()before it waits for anything. See ask for permission in a click. - iPhone and iPad: Web push only works in a web app that the person added to their Home Screen and opened from there. See iOS and iPadOS.
- Any browser: The browser doesn’t ask again after someone blocks notifications. See notifications are blocked.
Subscribing fails because of a different service worker
The plugin won’t replace a different service worker at the same path. Import our worker into your existing worker, or give our worker its own folder. See if your site already has a service worker.
Notifications arrive, but metrics don’t
The service worker reports delivered and opened metrics to the trackUrl you set in the plugin. If you register the service worker yourself, keep the ?track= query that the plugin adds to the worker’s URL. Also check that your trackUrl matches your account’s region.
Clicking the notification opens the wrong page
The notification only opens links that resolve to https:// URLs. A relative Link resolves against your site’s origin, not the service worker’s folder. For example, /bookings/123 opens https://www.yourbrand.com/bookings/123 on that site. A button without a URL opens Link. A button URL must be a full https:// address. If it isn’t, Customer.io removes that button and sends the rest of the notification. If Link is empty or doesn’t resolve to an https:// URL, the notification opens your site’s home page. Use full https:// addresses in Link and your button URLs to make the destination explicit for every person.
Only one of a person’s browsers gets the notification
Your message sends to the Last used device. See last used device or all devices.
A person who signed out still gets notifications
Call cioanalytics.reset() when people sign out. It removes the browser from their profile.