> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 网页推送 Webhooks

> 设置 HTTP webhooks 以在用户显示、点击或关闭网页推送通知时接收实时通知。包含 Chrome、Firefox 和 Safari 浏览器支持示例的完整指南。

## 概述

网页推送 Webhooks 允许您在用户与推送通知交互时接收实时的 HTTP POST 通知。当通知被显示、点击或关闭时，OneSignal 会自动将通知数据和任何自定义参数发送到您指定的 webhook URL。

<Warning>
  有关 Journey webhooks，请参阅我们的 [Journey webhooks](./journeys-webhook) 页面。
</Warning>

**主要优势：**

* 实时跟踪通知参与度
* 基于用户交互触发自动化工作流程
* 将通知数据与您的分析平台同步
* 为通知事件实现自定义业务逻辑

## 浏览器支持

| 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。

## 设置方法

<Tabs>
  <Tab title="仪表板配置（推荐给大多数用户）">
    <Steps>
      <Step>
        在您的 OneSignal 仪表板中导航到 **设置 > Web**
      </Step>

      <Step>
        启用“启用 webhooks”开关
      </Step>

      <Step>
        为您要跟踪的每个事件输入 webhook URL
      </Step>
    </Steps>

    <Frame caption="在您的 OneSignal 仪表板设置中启用 webhooks">
      <img src="https://mintcdn.com/onesignal/Xl2NHJvxakrK4JbL/images/docs/eb3347d-image.png?fit=max&auto=format&n=Xl2NHJvxakrK4JbL&q=85&s=c6c064fe350777ee479e0a22eb8a7ea0" width="1822" height="656" data-path="images/docs/eb3347d-image.png" />
    </Frame>
  </Tab>

  <Tab title="自定义代码集成">
    将 webhook 配置添加到您现有的 `OneSignal.init()` 方法中：

    ```javascript theme={null}
    // 添加到您现有的 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
      }
    });
    ```
  </Tab>
</Tabs>

<Info>确保您的 webhook URL 使用 HTTPS（Chrome 安全策略要求）。</Info>

## CORS 配置

`cors` 设置决定您的 webhook 端点接收的标头和数据：

* **`cors: false`（推荐）：** 更简单的设置，您的服务器上不需要 CORS 配置
* **`cors: true`：** 提供额外的标头，但需要您的服务器支持 CORS

**何时使用 `cors: true`：**

* 您需要 `Content-Type: application/json` 标头
* 您希望使用 `X-OneSignal-Event` 标头来更轻松地识别事件
* 您的服务器已经支持非简单请求的 CORS

## Webhook 请求格式

### 标准请求 (cors: false)

您的 webhook 端点接收带有以下载荷结构的 POST 请求：

```json theme={null}
{
  "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)

与上述相同的载荷，加上这些额外的标头：

```http theme={null}
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 调用（实现幂等性）

### 错误处理

```javascript theme={null}
// 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 数据来衡量不同通知策略的有效性