Weave Code
Webpush Laravel Package
laravel-notification-channels/webpush
Send web push notifications from Laravel with this notification channel. Supports the Push API across Chrome, Firefox, Edge, and Safari, VAPID keys, customizable titles, actions, TTL, subscription management on models, and automatic expired-subscription cleanup.
Laravel Web Push Notifications Channel lets you deliver browser push notifications through Laravel's native notification system. Add the HasPushSubscriptions trait to your notifiable model to store, update, and delete subscriptions, then send messages with a familiar channel API.
- VAPID support for secure browser authentication
- Cross-browser via the Push API (Chrome, Firefox, Edge, Safari)
- Rich message options — title, body, icon, actions, vibration, images, badges, and custom data
- Automatic cleanup of expired subscriptions when a send fails
- Publishable config for per-app customization
Frequently asked questions about Webpush
- How do I install laravel-notification-channels/webpush in a Laravel app?
- Install it with composer require laravel-notification-channels/webpush, then publish and run the migration that creates the push_subscriptions table. Next, add the NotificationChannels\WebPush\HasPushSubscriptions trait to your notifiable model, typically User. Finally run php artisan webpush:vapid to generate your VAPID keys and store them in your environment or secrets manager. The whole server-side setup is roughly a half-day including a local spike.
- Which Laravel and PHP versions does the webpush notification channel support?
- The current 11.x major supports Laravel 12 and 13, requires PHP 8.2 or newer, and depends on minishlink/web-push 10.0.1 or higher. Laravel 11 support was dropped in this major, so confirm your framework and PHP pair against the release notes before upgrading. Because the package tracks Laravel majors aggressively, its own majors are genuinely breaking, so pin versions and read the changelog.
- How do I send a web push notification from a Laravel notification class?
- Add WebPushChannel::class to the via() array of your notification and implement toWebPush() to return a WebPushMessage. The fluent builder lets you set title, body, icon, actions, TTL, vibrate, tag, badge, image, and custom data payloads. From there you send it like any other Laravel notification, and queued notifications work out of the box if your notification implements ShouldQueue.
- How do I generate and manage VAPID keys for web push in Laravel?
- Run php artisan webpush:vapid once and store the generated public and private keys in your .env file or a secrets manager, never in version control. The public key is bound to each subscription at subscribe time, so rotating keys silently invalidates every existing subscription and forces users to re-subscribe. Treat the key pair as long-lived infrastructure rather than a per-deploy config value, and make its storage a deliberate secrets-management decision.
- Why do web push notifications fail on Safari or iOS with a BadJwtToken error?
- Apple is stricter than Chrome and Firefox about the VAPID subject claim. VAPID_SUBJECT must be a valid https:// URL or a mailto: address with a real top-level domain, otherwise Apple returns BadJwtToken. Chrome and Firefox will often deliver successfully with an invalid subject, so this bug can slip through testing on desktop. Validate the subject in every environment, including staging.
- How do push subscriptions get saved on my User model?
- After adding the HasPushSubscriptions trait, the package stores subscriptions in a polymorphic push_subscriptions table, so you can attach them to User, Team, Device, or a tenant model without schema changes. Your front end captures the browser subscription and posts it to an endpoint that calls updatePushSubscription(). The config file lets you override the model, table, and database connection if you want push data isolated.
- Does the package clean up expired subscriptions automatically?
- Yes. When a push send returns a MessageSentReport flagged as expired, the package deletes the corresponding subscription row automatically. That keeps the table from filling with dead endpoints as users uninstall browsers or revoke permission. You should still decide on a retention policy for subscriptions belonging to users who never return.
- Do I still need a service worker to use web push in Laravel?
- Yes. The package covers only the server-side send path, which is roughly 30 percent of the delivery problem. You still need service worker registration, the permission prompt UX, subscription capture, and an endpoint that calls updatePushSubscription(). Budget the Composer install as a half-day and the browser integration as a sprint.
- What breaking changes came with the latest major of the webpush channel?
- Version 11.x changes the default content encoding to aesgcm128 when the stored encoding is null, casts content_encoding to a ContentEncoding enum, and requires getOptions() on WebPushMessageInterface. It also drops Laravel 11 and requires PHP 8.2 with minishlink/web-push 10.0.1 or later. If you implement custom message classes or store subscriptions from an older version, plan a migration rather than a blind composer update.
- How do I customize TTL, actions, vibration, or the tag on a web push message?
- The WebPushMessage builder exposes fluent methods for title, body, icon, badge, image, actions, TTL, vibrate, tag, and data. For anything not covered, the options() method passes arguments straight through to web-push-php, so advanced web-push features remain reachable. Delivery outcomes surface only through the sent and failed notification events, so add your own logging or metrics if you need visibility.
Weaver
How can I help you explore Laravel packages today?