​

Overview

Web Push Webhooks allow you to receive real-time HTTP POST notifications whenever users interact with your push notifications. When a notification is displayed, clicked, or dismissed, OneSignal automatically sends the notification data and any custom parameters to your specified webhook URL.

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

​

Browser Support

​

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

// 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
  }
});

​

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

​

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