# Webhook 回调事件 (/zh-CN/realtime-media/meeting/reference/webhook-events)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

本文介绍智能云会议 Webhook 回调事件。

Webhook 是一种基于 HTTP 协议的回调机制，允许服务端主动推送数据。当你订阅的事件发生时，声网智能云会议服务器会将事件消息发送给声网消息通知服务器，然后声网消息通知服务器会通过 HTTPS POST 请求将事件通知投递给你的服务器。

调用[创建房间](/zh-CN/api-reference/meeting/restful/api/create-room) API 时，通过 `roomProperties.webhookConfig` 字段设置接收 Webhook 事件的服务器地址和订阅事件列表后，你可以在这些事件发生后收到回调通知。

## 回调格式 [#回调格式]

回调会通过 HTTPS POST 请求发送到你的服务器，因此你的服务器必须提供 HTTPS 地址，并支持接收 POST 请求。

回调请求的 Header 中包含以下字段：

- `Content-Type`：`application/json`。代表指定请求 Body 的类型为 JSON，以 `UTF-8` 字符编码进行编码。

回调请求的 Body 中包含以下字段：

|字段|类型|描述|
|---|---|---|
|`roomUuid`|String|会议房间 UUID。|
|`cmd`|Integer| [事件类型](/zh-CN/realtime-media/meeting/reference/webhook-events)|
|`sequence`|Integer|事件序号，用于标识同一个房间内发生的事件。在同一个房间内，`sequence` 不会重复，并且会自动递增，以确保事件的有序性。|
|`version`|Integer|事件版本号。|
|`ts`|Integer|事件发生的 Unix 时间戳。UTC 时间，单位为毫秒。|
|`data`|Object|事件的具体数据，不同事件会包含不同数据，详见[事件类型](/zh-CN/realtime-media/meeting/reference/webhook-events)。|

```json
{
  "roomUuid": "xxx",
  // highlight-start
  "cmd": 1,
  // highlight-end
  "sequence": 1,
  "version": 1,
  "ts": 1611564500488,
  // highlight-start
  "data": {
    ...
  }
  // highlight-end
}
```

## 事件类型 [#事件类型]

`cmd` 的不同数值代表不同的事件，每个事件的具体数据在 `data` 字段中展示。

### 会议状态变更事件 [#会议状态变更事件]

cmd = 1，代表会议状态变更事件。

```json
{
  ...
  "data": {
    "startTime": 1611561776588,
    "state": 1
  }
}
```

| 字段 | 类型 | 描述 |
| --- | --- | --- |
| `state` | Integer | [webhook-events-restful-html-0-1-2 details](#table-slot-webhook-events-restful-html-0-1-2) |
| `startTime` | Number | 会议开始时间，Unix 时间戳（毫秒），UTC 时间。仅当会议进行中（state = 1）时有该字段。 |
| `endTime` | Number | 会议结束时间，Unix 时间戳（毫秒），UTC 时间。仅当会议已结束（state = 2）时有该字段。 |
| `closeTime` | Number | 会议关闭时间，Unix 时间戳（毫秒），UTC 时间。仅当会议房间已关闭（state = 3）时有该字段。 |

<a id="table-slot-webhook-events-restful-html-0-1-2"></a>

**webhook-events-restful-html-0-1-2 details**

当前会议状态：

- `0`：会议未开始。
- `1`：会议进行中。
- `2`：会议已结束。会议持续时长结束时，当前会议进入该状态，此时用户依然可以正常进入会议和逗留。
- `3`：会议房间关闭。会议持续时长结束后，会议拖堂时间也结束时，当前会议进入该状态，此时会议内用户会被踢出，用户也无法再进入会议。

### 用户进出会议事件 [#用户进出会议事件]

cmd = 20，代表用户进出会议事件。

```json
{
  ...
  "data": {
    "total": 2,
    "onlineUsers": [
      {
        "userName": "user_name_1",
        "userUuid": "uuid_1",
        "role": "host",
        "userProperties": {},
        "streamUuid": "stream_uuid_1",
        "type": 1,
        "updateTime": 1611561776588
      }
    ],
    "offlineUsers": [
      {
        "userName": "user_name_2",
        "userUuid": "uuid_2",
        "role": "participant",
        "userProperties": {},
        "streamUuid": "stream_uuid_2",
        "type": 1,
        "updateTime": 1611561776588
      }
    ]
  }
}
```

|字段|类型|描述|
|---|---|---|
|`total`|Integer|进入和退出会议的用户总数。|
|`onlineUsers`|Object Array|进入会议的用户的具体信息。|
|`offlineUsers`|Object Array|退出会议的用户的具体信息。|

进出会议的用户具体信息如下：

| 字段 | 类型 | 描述 |
| --- | --- | --- |
| `userName` | String | 用户在会议房间中的名称。 |
| `userUuid` | String | 用户 UUID。 |
| `role` | String | [webhook-events-restful-html-1-3-2 details](#table-slot-webhook-events-restful-html-1-3-2) |
| `userProperties` | Object | 用户属性。 |
| `streamUuid` | String | 用户流的 UUID。 |
| `type` | Integer | [webhook-events-restful-html-1-6-2 details](#table-slot-webhook-events-restful-html-1-6-2) |
| `updateTime` | Number | 用户进出会议时的 Unix 时间戳，单位为毫秒，UTC 时间。 |

<a id="table-slot-webhook-events-restful-html-1-3-2"></a>

**webhook-events-restful-html-1-3-2 details**

用户在会议房间中的角色：

- `host`：主持人。
- `cohost`：助理主持人。
- `participant`：参会人。

<a id="table-slot-webhook-events-restful-html-1-6-2"></a>

**webhook-events-restful-html-1-6-2 details**

对于进入房间的用户，该字段表示用户进入的方式：

- `1`：正常进入。

对于退出房间的用户，该字段标识用户退出的方式：

- `1`：由于客户端原因退出会议，例如正常离开会议、应用被强制关闭或网络状况不佳导致断线。
- `2`：被踢出会议。

### 页面录制状态变更事件 [#页面录制状态变更事件]

cmd = 1001，代表页面录制状态变更事件。

```json
{
  ...
  "data": {
    "recordId": "record_id",
    "sid": "session_id",
    "resourceId": "resource_id",
    "state": 1,
    "startTime": 1611564500488,
    "onhold": false
  }
}
```

| 字段 | 类型 | 描述 |
| --- | --- | --- |
| `recordId` | String | 一次录制的唯一标识符。调用设置录制状态 API 开始录制并结束录制，视为一次录制。仅当录制进行中（state = 1）时有该字段。 |
| `sid` | String | 声网云端录制服务的 `sid`。仅当录制进行中（state = 1）时有该字段。 |
| `resourceId` | String | 声网云端录制服务的 `resourceId`。仅当录制进行中（state = 1）时有该字段。 |
| `state` | Integer | [webhook-events-restful-html-2-4-2 details](#table-slot-webhook-events-restful-html-2-4-2) |
| `startTime` | Number | 录制开始时间，Unix 时间戳（毫秒），UTC 时间。录制开始后该字段有值。 |
| `endTime` | Number | 录制结束时间，Unix 时间戳（毫秒），UTC 时间。录制结束后有该字段。 |
| `retryTimes` | Integer | 当前重试次数。设置过重试次数后，才有该字段。 |
| `ready` | Boolean | 待录制的页面加载完成时，该字段为 `true`；否则，没有该字段。 |
| `onhold` | Boolean | [webhook-events-restful-html-2-9-2 details](#table-slot-webhook-events-restful-html-2-9-2) |

<a id="table-slot-webhook-events-restful-html-2-4-2"></a>

**webhook-events-restful-html-2-4-2 details**

当前录制状态：

- `0`：录制已结束。
- `1`：录制进行中。

<a id="table-slot-webhook-events-restful-html-2-9-2"></a>

**webhook-events-restful-html-2-9-2 details**

启动录制任务时是否暂停了录制：

- `true`：暂停录制中。
- `false`：正常录制中。

### 页面录制文件上传成功事件 [#页面录制文件上传成功事件]

cmd = 1002，代表页面录制文件上传成功事件。

```json
{
  ...
  "data": {
    "recordId": "record_id",
    "addUrl": "https://example1.com/example1.mp4",
    "recordDetails": [
      {
        "url": "https://example2.com/example2.mp4"
      }
    ],
    "allUploaded": true
  }
}
```

|字段|类型|描述|
|---|---|---|
|`recordId`|String|一次录制的唯一标识符。|
|`addUrl`|String|本次新增的录制文件地址。|
|`recordDetails`|Object Array| 录制文件列表。|
|`recordDetails.url`|String| 当前所有录制文件地址（含本次新增的录制文件地址）。|
|`allUploaded`|Boolean|所有文件都上传完成时，该字段为 `true`；否则，没有该字段。|

### AI 会议纪要生成成功事件 [#ai-会议纪要生成成功事件]

cmd = 1003，代表 AI 会议纪要生成成功事件。

```json
{
  ...
  "data": {
    "agentId": "agent_id",
    "startTime": 1611564500488,
    "endTime": 1611564500488,
    "summary": ""
  }
}
```

| 字段  | 类型  | 描述  |
|---|---|---|
|`agentId`|String|AI 会议纪要的任务 ID。|
|`startTime`|Long|AI 会议纪要开始时的 Unix 时间戳。UTC 时间，单位为毫秒。|
|`endTime`|Long|AI 会议纪要结束时的 Unix 时间戳。UTC 时间，单位为毫秒。|
|`summary`|String|AI 会议纪要的内容。|