网页推送 Webhooks 允许您在用户与推送通知交互时接收实时的 HTTP POST 通知。当通知被显示、点击或关闭时，OneSignal 会自动将通知数据和任何自定义参数发送到您指定的 webhook URL。
主要优势：
- 实时跟踪通知参与度
- 基于用户交互触发自动化工作流程
- 将通知数据与您的分析平台同步
- 为通知事件实现自定义业务逻辑
浏览器支持
| Browser | Platform Support | Webhook Events Available |
|---|
| Chrome | macOS, Windows, Android | 所有事件（显示、点击、关闭） |
| Firefox | macOS, Windows, Android | 显示和点击事件 |
| Safari | 不支持 | 无 |
可用的 Webhook 事件
notification.willDisplay
在通知出现在用户屏幕上后立即触发。
使用场景： 跟踪投递率、记录展示数据、触发后续活动
notification.clicked
当用户点击通知正文或任何操作按钮时触发。
使用场景： 跟踪参与率、触发转化事件、将用户重定向到特定内容
notification.dismissed
当用户主动关闭通知或通知自动过期时触发。
浏览器支持： 仅 Chrome
使用场景： 跟踪关闭率、优化通知时间、A/B 测试通知内容
重要提示： 点击通知正文或操作按钮不会触发关闭 webhook。
设置方法
在您的 OneSignal 仪表板中导航到 设置 > Web
将 webhook 配置添加到您现有的 OneSignal.init() 方法中：// 添加到您现有的 OneSignal 初始化 - 请勿两次调用 init
OneSignal.init({
// 您的其他现有设置在此处
webhooks: {
cors: false, // 推荐：除非您需要自定义标头，否则保持为 false
'notification.willDisplay': 'https://yoursite.com/webhook/display',
'notification.clicked': 'https://yoursite.com/webhook/click',
'notification.dismissed': 'https://yoursite.com/webhook/dismiss' // Chrome only
}
});
确保您的 webhook URL 使用 HTTPS（Chrome 安全策略要求）。
CORS 配置
cors 设置决定您的 webhook 端点接收的标头和数据：
cors: false（推荐）： 更简单的设置，您的服务器上不需要 CORS 配置cors: true： 提供额外的标头，但需要您的服务器支持 CORS
何时使用 cors: true：
- 您需要
Content-Type: application/json 标头
- 您希望使用
X-OneSignal-Event 标头来更轻松地识别事件
- 您的服务器已经支持非简单请求的 CORS
Webhook 请求格式
标准请求 (cors: false)
您的 webhook 端点接收带有以下载荷结构的 POST 请求：
{
"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"
}
增强请求 (cors: true)
与上述相同的载荷，加上这些额外的标头：
Content-Type: application/json
X-OneSignal-Event: notification.clicked
载荷字段参考
| 字段 | 类型 | 描述 | 始终存在 |
|---|
event | string | 触发 webhook 的事件类型 | ✅ |
notificationId | string | OneSignal 通知唯一标识符 | ✅ |
heading | string | 通知标题 | 仅在提供时 |
content | string | 通知消息正文 | 仅在提供时 |
additionalData | object | 与通知一起发送的自定义数据 | 仅在提供时 |
actionId | string | 被点击操作按钮的 ID（空字符串 = 点击通知正文） | 仅点击事件 |
url | string | 通知的启动 URL | 仅在提供时 |
subscriptionId | string | OneSignal 用户/订阅 ID | 仅开启 CORS 时 |
实施最佳实践
Webhook 端点要求
安全性：
- 仅使用 HTTPS URL（HTTP URL 将被 Chrome 阻止）
- 为您的 webhook 端点实现适当的身份验证/校验
- 考虑使用速率限制来处理大量通知
响应要求：
- 成功处理时返回 HTTP 200 状态
- 在10秒内响应以避免超时
- 优雅地处理重复的 webhook 调用（实现幂等性）
错误处理
// Example webhook endpoint (Node.js/Express)
app.post('/webhook/notification', (req, res) => {
try {
const { event, notificationId, additionalData } = req.body;
// 验证必需字段
if (!event || !notificationId) {
return res.status(400).json({ error: 'Missing required fields' });
}
// 处理 webhook 数据
processNotificationEvent(req.body);
// 始终响应 200 OK
res.status(200).json({ success: true });
} catch (error) {
console.error('Webhook processing error:', error);
res.status(500).json({ error: 'Internal server error' });
}
});
常见问题和解决方案
Webhooks 未触发
可能的原因：
- 在所有包含 OneSignal 初始化的页面上都没有 webhook 代码
- 用户在添加 webhook 代码后尚未访问包含 webhook 代码的页面
- 未满足 HTTPS 要求
- 服务器返回非 200 状态码
解决方案： 确保在所有激活通知的页面上，您的 OneSignal init 代码中都包含 webhook 配置。
Webhooks 中缺少数据
原因： Webhooks 只跟踪访问包含激活 webhook 配置页面的用户事件。
解决方案： 将 webhook 代码部署到所有包含 OneSignal 的页面，而不仅仅是特定的着陆页。
重复的 Webhook 调用
原因： 网络问题或浏览器行为可能导致重复请求。
解决方案： 使用 notificationId 字段实现幂等性来对事件去重。
Webhook 限制
- 每个事件仅一个 webhook URL： 您不能为同一事件类型设置多个 webhook URL
- 仅支持 HTTPS： 由于浏览器安全限制，HTTP URL 将无法工作
- 仅 Chrome 支持关闭跟踪：
notification.dismissed 事件仅在 Chrome 中有效
- 页面依赖性： 用户必须访问包含激活 webhook 代码的页面才能实现跟踪
测试您的 Webhooks
- 通过您的 OneSignal 仪表板发送测试通知
- 监控您的 webhook 端点的传入请求
- 验证载荷结构是否符合您的期望
- 测试不同场景：
- 通知显示
- 点击通知正文
- 点击操作按钮（如果已配置）
- 关闭通知（仅 Chrome）
下一步
设置 webhooks 后，请考虑：
- 分析集成： 将 webhook 数据转发到您的分析平台
- 用户分组： 使用 webhook 事件根据参与度创建用户分组
- 自动化工作流程： 基于推送通知交互触发邮件活动或应用通知
- A/B 测试： 使用 webhook 数据来衡量不同通知策略的有效性
