---
url: /zh/paas/user-notify.md
description: |
  介绍 PAAS 版云原生构建的用户通知功能， 支持订阅系统事件并配置回调地址， 将构建事件通知推送至第三方消息服务。
---
## 概述

`云原生构建` 支持用户订阅系统事件，将通知消息推送至指定回调地址。

## 工作流程

```mermaid
  sequenceDiagram
    participant 云原生构建
    participant 通知回调地址
    participant 第三方消息服务
    participant 需要通知的用户
    云原生构建->>通知回调地址: 1. send user notify message
    通知回调地址->>第三方消息服务: 2. parse the message and send to message service
    第三方消息服务->>需要通知的用户: 3. notify user and show the message
```

## 通知配置

登录 admin 管理平台，
依次点击「后台管理 → 系统钩子配置 → 新建系统钩子」进入配置页面。

![user\_notify\_settings](/images/admin-hook-setting.png)

配置参数如下：

| 参数名  | 类型     | 必选 | 描述                    |
| :----: | :-----: | :--: | :--------------------- |
| 链接   | String  | Y    | 回调地址，接收通知消息    |
| 类型   | String  | Y    | 选择「用户通知」         |
| 触发   | String  | Y    | 订阅的事件类型，支持多选  |
| 令牌   | String  | N    | 回调地址的鉴权令牌，选填  |

## 事件类型

`云原生构建` 支持以下事件类型（不限于）：

* pull request
  * 新增评论
  * 新增指派人
  * 新增审核人
  * 状态变更
  * 新增评审
* issue
  * 新增评论
  * 新增指派人
  * 状态变更
* 仓库
  * 归档
  * 删除
  * 转移
  * 成员角色变更
* 组织
  * 转移
  * 成员角色变更
* 用户
  * @用户

## 通知消息结构

### 通知消息头

* `Content-Type`: `application/json;charset=utf-8`
* `X-CNB-Event`: `System Hook`，标识通知消息事件类型
* `X-CNB-Token`: 如配置了鉴权 Token（详见「通知配置」），则包含此字段

### 通知 body

```json
{
  "touser": "UserID1|UserID2|UserID3", 
  "msgtype": "text", 
  "text": {
    "content": "有新的 PR 待处理"
  }
}
```

参数说明：

| 参数名   | 类型     | 必选 | 描述                                        |
| :-----: | :-----: | :--: | :------------------------------------------- |
| touser  | String  | Y    | 接收消息的成员 ID 列表（多个用 `\|` 分隔，最多 1000 个） |
| msgtype | String  | Y    | 消息类型，固定为 text                        |
| content | String  | Y    | 消息内容，最长 2048 字节                      |

### 通知消息示例

以 Pull Request 新增评审为例，当评审人员批准 PR 时，会发送以下通知：

```text
admin1 批准了 PR #1

feat: init
https://cnbprod.alpha.qq.com/test/test-repo/-/pulls/1
```

请求 body 内容为：

```json
{
  "touser": "123",
  "msgtype": "text",
  "text": {
    "content": "admin1 批准了 PR #1\n\nfeat: init\nhttps://cnbprod.alpha.qq.com/test/test-repo/-/pulls/1"
  }
}
```