跳转到主要内容

概述

网页推送 Webhooks 允许您在用户与推送通知交互时接收实时的 HTTP POST 通知。当通知被显示、点击或关闭时,OneSignal 会自动将通知数据和任何自定义参数发送到您指定的 webhook URL。
有关 Journey webhooks,请参阅我们的 Journey webhooks 页面。
主要优势:
  • 实时跟踪通知参与度
  • 基于用户交互触发自动化工作流程
  • 将通知数据与您的分析平台同步
  • 为通知事件实现自定义业务逻辑

浏览器支持

BrowserPlatform SupportWebhook Events Available
ChromemacOS, Windows, Android所有事件(显示、点击、关闭)
FirefoxmacOS, Windows, Android显示和点击事件
Safari不支持

可用的 Webhook 事件

notification.willDisplay

在通知出现在用户屏幕上后立即触发。 使用场景: 跟踪投递率、记录展示数据、触发后续活动

notification.clicked

当用户点击通知正文或任何操作按钮时触发。 使用场景: 跟踪参与率、触发转化事件、将用户重定向到特定内容

notification.dismissed

当用户主动关闭通知或通知自动过期时触发。 浏览器支持: 仅 Chrome 使用场景: 跟踪关闭率、优化通知时间、A/B 测试通知内容 重要提示: 点击通知正文或操作按钮不会触发关闭 webhook。

设置方法

  • 仪表板配置(推荐给大多数用户)
  • 自定义代码集成
1

在您的 OneSignal 仪表板中导航到 设置 > Web
2

启用“启用 webhooks”开关
3

为您要跟踪的每个事件输入 webhook URL

在您的 OneSignal 仪表板设置中启用 webhooks

确保您的 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

载荷字段参考

字段类型描述始终存在
eventstring触发 webhook 的事件类型
notificationIdstringOneSignal 通知唯一标识符
headingstring通知标题仅在提供时
contentstring通知消息正文仅在提供时
additionalDataobject与通知一起发送的自定义数据仅在提供时
actionIdstring被点击操作按钮的 ID(空字符串 = 点击通知正文)仅点击事件
urlstring通知的启动 URL仅在提供时
subscriptionIdstringOneSignal 用户/订阅 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

  1. 通过您的 OneSignal 仪表板发送测试通知
  2. 监控您的 webhook 端点的传入请求
  3. 验证载荷结构是否符合您的期望
  4. 测试不同场景:
    • 通知显示
    • 点击通知正文
    • 点击操作按钮(如果已配置)
    • 关闭通知(仅 Chrome)

下一步

设置 webhooks 后,请考虑:
  • 分析集成: 将 webhook 数据转发到您的分析平台
  • 用户分组: 使用 webhook 事件根据参与度创建用户分组
  • 自动化工作流程: 基于推送通知交互触发邮件活动或应用通知
  • A/B 测试: 使用 webhook 数据来衡量不同通知策略的有效性
I