Web push webhooks

Set up HTTP webhooks to receive real-time notifications when users display, click, or dismiss web push notifications. Complete guide with examples for Chrome, Firefox, and Safari browser support.

Overview

Web push webhooks are client-side callbacks the browser fires through the OneSignal Web SDK whenever users interact with your web push notifications (displayed, clicked, or dismissed). The browser sends the notification data and any custom parameters to the webhook URL you configure per web app. You set them up in Settings > Web or in your Web SDK init() call.

Most customers want Event Streams, not web push webhooks. Event Streams sends message events (sent, clicked, bounced, and more) across every channel to your servers in real time, and is the recommended way to get OneSignal data into your own systems. Web push webhooks are an older, browser-only feature kept for teams that specifically need client-side web push callbacks.

Key Benefits:

• Track notification engagement in real-time
• Trigger automated workflows based on user interactions
• Sync notification data with your analytics platform
• Implement custom business logic for notification events

Which webhook do you need?

OneSignal has several distinct features that are commonly called “webhooks”. They live in different places and do different things. This page covers web push webhooks: browser-side callbacks that fire only for web push interactions. They do not apply to mobile app push, email, SMS, in-app messages, or server-side events. For most integrations, use Event Streams. To choose between the options:

Feature	Use it when you want to…	Where it’s configured
Event Streams (recommended)	Stream message events across all channels (sent, clicked, bounced, etc.) to your systems in real time	Data > Event Streams
Journey webhooks	Send an HTTP request to your server when a user reaches a step in a Journey	Data > Webhooks, then added to a Journey with the Webhook node
Web push webhooks (this page)	Receive browser callbacks when web push notifications are displayed, clicked, or dismissed	Settings > Web, or the Web SDK init() call

Browser Support

Browser	Platform Support	Webhook Events Available
Chrome	macOS, Windows, Android	All events (display, click, dismiss)
Firefox	macOS, Windows, Android	Display and click events
Safari	Not supported	None

Available Webhook Events

notification.willDisplay

Triggered immediately after a notification appears on the user’s screen.

Use cases: Track delivery rates, log impression data, trigger follow-up campaigns

notification.clicked

Triggered when a user clicks on the notification body or any action button.

Use cases: Track engagement rates, trigger conversion events, redirect users to specific content

notification.dismissed

Triggered when a user actively dismisses a notification or when it expires automatically.

Browser support: Chrome only Use cases: Track dismissal rates, optimize notification timing, A/B test notification content

Important: Clicking the notification body or action buttons does NOT trigger the dismissed webhook.

Setup Methods

Dashboard Configuration (Recommended for Most Users)

1. Navigate to Settings > Web in your OneSignal dashboard

2. Enable the “Enable webhooks” toggle

3. Enter your webhook URLs for each event you want to track

Enable webhooks in your OneSignal dashboard settings

Custom Code Integration

Add webhook configuration to your existing OneSignal.init() method:

// Add to your existing OneSignal initialization - do NOT call init twice
OneSignal.init({
  // Your other existing settings here
  webhooks: {
    cors: false, // Recommended: leave as false unless you need custom headers
    'notification.willDisplay': 'https://yoursite.com/webhook/display',
    'notification.clicked': 'https://yoursite.com/webhook/click',
    'notification.dismissed': 'https://yoursite.com/webhook/dismiss' // Chrome only
  }
});

Make sure your webhook URLs are HTTPS (required by Chrome’s security policies).

CORS Configuration

The cors setting determines what headers and data your webhook endpoint receives:

• cors: false (Recommended): Simpler setup, no CORS configuration needed on your server
• cors: true: Provides additional headers but requires CORS support on your server

When to use cors: true:

• You need the Content-Type: application/json header
• You want the X-OneSignal-Event header for easier event identification
• Your server already supports CORS for non-simple requests

Webhook Request Format

Standard Request (cors: false)

Your webhook endpoint receives a POST request with this payload structure:

{
  "event": "notification.clicked",
  "notificationId": "ed46884e-0e3f-4373-9e11-e28f27746d3d",
  "heading": "Your notification title",
  "content": "Your notification message",
  "additionalData": {
    "userId": "12345",
    "campaignId": "summer-sale",
    "customField": "customValue"
  },
  "actionId": "buy-now-button",
  "url": "https://yoursite.com/product/123"
}

Enhanced Request (cors: true)

Same payload as above, plus these additional headers:

Content-Type: application/json
X-OneSignal-Event: notification.clicked

Payload Field Reference

Field	Type	Description	Always Present
event	string	Event type that triggered the webhook	✅
notificationId	string	Unique OneSignal notification identifier	✅
heading	string	Notification title	Only if provided
content	string	Notification message body	Only if provided
additionalData	object	Custom data sent with notification	Only if provided
actionId	string	ID of clicked action button (empty string = notification body clicked)	Click events only
url	string	Launch URL for the notification	Only if provided
subscriptionId	string	OneSignal user/subscription ID	CORS enabled only

Implementation Best Practices

Webhook Endpoint Requirements

Security:

• Use HTTPS URLs only (HTTP URLs will be blocked by Chrome)
• Implement proper authentication/validation for your webhook endpoints
• Consider rate limiting to handle high-volume notifications

Response Requirements:

• Return HTTP 200 status for successful processing
• Respond within 10 seconds to avoid timeouts
• Handle duplicate webhook calls gracefully (implement idempotency)

Error Handling

// Example webhook endpoint (Node.js/Express)
app.post('/webhook/notification', (req, res) => {
  try {
    const { event, notificationId, additionalData } = req.body;

    // Validate required fields
    if (!event || !notificationId) {
      return res.status(400).json({ error: 'Missing required fields' });
    }

    // Process the webhook data
    processNotificationEvent(req.body);

    // Always respond with 200 OK
    res.status(200).json({ success: true });
  } catch (error) {
    console.error('Webhook processing error:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
});

Common Issues and Solutions

Webhooks Not Firing

Possible causes:

• Webhook code not present on all pages with OneSignal initialization
• User hasn’t visited a page with webhook code after it was added
• HTTPS requirement not met
• Server returning non-200 status codes

Solution: Ensure webhook configuration is included in your OneSignal init code on all pages where notifications are active.

Missing Data in Webhooks

Cause: Webhooks only track events for users who visit pages with the webhook configuration active.

Solution: Deploy webhook code to all pages with OneSignal, not just specific landing pages.

Duplicate Webhook Calls

Cause: Network issues or browser behavior may cause duplicate requests.

Solution: Implement idempotency using the notificationId field to deduplicate events.

Webhook Limitations

• One webhook URL per event: You cannot set multiple webhook URLs for the same event type
• HTTPS only: HTTP URLs will not work due to browser security restrictions
• Chrome-only dismissal tracking: The notification.dismissed event only works in Chrome
• Page dependency: Users must visit pages with webhook code active for tracking to work

Testing Your Webhooks

1. Send a test notification through your OneSignal dashboard
2. Monitor your webhook endpoint for incoming requests
3. Verify payload structure matches your expectations
4. Test different scenarios:
   • Notification display
   • Clicking notification body
   • Clicking action buttons (if configured)
   • Dismissing notifications (Chrome only)

Next Steps

After setting up webhooks, consider:

• Analytics Integration: Forward webhook data to your analytics platform
• User Segmentation: Use webhook events to create user segments based on engagement
• Automated Workflows: Trigger email campaigns or app notifications based on push notification interactions
• A/B Testing: Use webhook data to measure the effectiveness of different notification strategies