---
url: /zh/paas/user-notify.md
---
## 概述

`云原生构建` 支持用户订阅系统事件，向用户配置的回调地址发送消息。

## 工作流程

```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
  * 新增评论
  * 新增指派人
  * 状态变更
* 仓库
  * 归档
  * 删除
  * 转移
  * 成员角色变更
* 组织
  * 转移
  * 成员角色变更
* 用户
  * @用户

## 通知消息结构

### 通知 header 头

* `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://cnb.share.ralphlauren.cn/test/test-repo/-/pulls/1
```

请求 body 内容为:

```json
{
  "touser": "123",
  "msgtype": "text",
  "text": {
    "content": "admin1 批准了 PR #1\n\nfeat: init\nhttps://cnb.share.ralphlauren.cn/test/test-repo/-/pulls/1"
  }
}
```