# Webhook 配置说明文档

## 概述

Webhook 配置用于设置 OpenIM 服务器在特定事件发生时的回调通知。配置支持从数据库动态读取，每小时自动刷新一次。如果数据库中没有配置或配置无效，将使用 `config/webhooks.yml` 中的默认配置。

## 配置结构

### 基础字段

- **url** (string, 必填): Webhook 回调服务器的地址，所有回调请求都会发送到这个地址

### BeforeConfig（前置回调配置）

前置回调在操作执行前触发，可以阻止或修改操作。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| enable | boolean | 是 | 是否启用该回调 |
| timeout | integer | 是 | 超时时间（秒） |
| failedContinue | boolean | 是 | 回调失败时是否继续执行原操作（true=继续，false=停止） |
| deniedTypes | array[int32] | 否 | 不触发回调的消息类型列表，空数组表示所有类型都触发 |

### AfterConfig（后置回调配置）

后置回调在操作执行后触发，用于通知和记录。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| enable | boolean | 是 | 是否启用该回调 |
| timeout | integer | 是 | 超时时间（秒） |
| attentionIds | array[string] | 否 | 仅对指定用户ID或群组ID触发回调，空数组表示所有都触发 |
| deniedTypes | array[int32] | 否 | 不触发回调的消息类型列表，空数组表示所有类型都触发 |

## 支持的回调事件

### 消息相关

| 事件名称 | 类型 | 说明 |
|---------|------|------|
| beforeSendSingleMsg | BeforeConfig | 发送单聊消息前 |
| afterSendSingleMsg | AfterConfig | 发送单聊消息后 |
| beforeSendGroupMsg | BeforeConfig | 发送群聊消息前 |
| afterSendGroupMsg | AfterConfig | 发送群聊消息后 |
| beforeMsgModify | BeforeConfig | 修改消息前（可用于消息过滤） |
| afterMsgSaveDB | AfterConfig | 消息保存到数据库后 |
| afterRevokeMsg | AfterConfig | 撤回消息后 |
| afterGroupMsgRevoke | AfterConfig | 撤回群消息后 |
| afterGroupMsgRead | AfterConfig | 群消息已读后 |
| afterSingleMsgRead | AfterConfig | 单聊消息已读后 |

### 用户相关

| 事件名称 | 类型 | 说明 |
|---------|------|------|
| beforeUserRegister | BeforeConfig | 用户注册前 |
| afterUserRegister | AfterConfig | 用户注册后 |
| beforeUpdateUserInfo | BeforeConfig | 更新用户信息前 |
| afterUpdateUserInfo | AfterConfig | 更新用户信息后 |
| beforeUpdateUserInfoEx | BeforeConfig | 更新用户扩展信息前 |
| afterUpdateUserInfoEx | AfterConfig | 更新用户扩展信息后 |
| afterUserOnline | AfterConfig | 用户上线后 |
| afterUserOffline | AfterConfig | 用户下线后 |
| afterUserKickOff | AfterConfig | 用户被踢下线后 |

### 群组相关

| 事件名称 | 类型 | 说明 |
|---------|------|------|
| beforeCreateGroup | BeforeConfig | 创建群组前 |
| afterCreateGroup | AfterConfig | 创建群组后 |
| beforeSetGroupInfo | BeforeConfig | 设置群组信息前 |
| afterSetGroupInfo | AfterConfig | 设置群组信息后 |
| beforeSetGroupInfoEx | BeforeConfig | 设置群组扩展信息前 |
| afterSetGroupInfoEx | AfterConfig | 设置群组扩展信息后 |
| beforeMemberJoinGroup | BeforeConfig | 成员加入群组前 |
| afterJoinGroup | AfterConfig | 成员加入群组后 |
| beforeApplyJoinGroup | BeforeConfig | 申请加入群组前 |
| beforeInviteUserToGroup | BeforeConfig | 邀请用户加入群组前 |
| afterQuitGroup | AfterConfig | 退出群组后 |
| afterKickGroupMember | AfterConfig | 踢出群成员后 |
| afterDismissGroup | AfterConfig | 解散群组后 |
| afterTransferGroupOwner | AfterConfig | 转移群主后 |
| beforeSetGroupMemberInfo | BeforeConfig | 设置群成员信息前 |
| afterSetGroupMemberInfo | AfterConfig | 设置群成员信息后 |

### 好友相关

| 事件名称 | 类型 | 说明 |
|---------|------|------|
| beforeAddFriend | BeforeConfig | 添加好友前 |
| afterAddFriend | AfterConfig | 添加好友后 |
| beforeAddFriendAgree | BeforeConfig | 同意好友申请前 |
| afterAddFriendAgree | AfterConfig | 同意好友申请后 |
| afterDeleteFriend | AfterConfig | 删除好友后 |
| beforeSetFriendRemark | BeforeConfig | 设置好友备注前 |
| afterSetFriendRemark | AfterConfig | 设置好友备注后 |
| beforeImportFriends | BeforeConfig | 导入好友前 |
| afterImportFriends | AfterConfig | 导入好友后 |
| beforeAddBlack | BeforeConfig | 加入黑名单前 |
| afterRemoveBlack | AfterConfig | 移除黑名单后 |

### 推送相关

| 事件名称 | 类型 | 说明 |
|---------|------|------|
| beforeOfflinePush | BeforeConfig | 离线推送前 |
| beforeOnlinePush | BeforeConfig | 在线推送前 |
| beforeGroupOnlinePush | BeforeConfig | 群组在线推送前 |

### 会话相关

| 事件名称 | 类型 | 说明 |
|---------|------|------|
| beforeCreateSingleChatConversations | BeforeConfig | 创建单聊会话前 |
| afterCreateSingleChatConversations | AfterConfig | 创建单聊会话后 |
| beforeCreateGroupChatConversations | BeforeConfig | 创建群聊会话前 |
| afterCreateGroupChatConversations | AfterConfig | 创建群聊会话后 |

## JSON 配置示例

### 完整配置示例

```json
{
  "url": "http://your-webhook-server:8080/callback",
  "beforeSendSingleMsg": {
    "enable": true,
    "timeout": 5,
    "failedContinue": true,
    "deniedTypes": []
  },
  "afterSendSingleMsg": {
    "enable": true,
    "timeout": 5,
    "attentionIds": [],
    "deniedTypes": []
  },
  "beforeSendGroupMsg": {
    "enable": true,
    "timeout": 5,
    "failedContinue": true,
    "deniedTypes": []
  },
  "afterSendGroupMsg": {
    "enable": true,
    "timeout": 5,
    "attentionIds": [],
    "deniedTypes": []
  },
  "beforeMsgModify": {
    "enable": true,
    "timeout": 5,
    "failedContinue": true,
    "deniedTypes": []
  },
  "afterMsgSaveDB": {
    "enable": false,
    "timeout": 5,
    "attentionIds": [],
    "deniedTypes": []
  },
  "afterUserOnline": {
    "enable": true,
    "timeout": 5,
    "attentionIds": [],
    "deniedTypes": []
  },
  "afterUserOffline": {
    "enable": true,
    "timeout": 5,
    "attentionIds": [],
    "deniedTypes": []
  },
  "afterUserKickOff": {
    "enable": false,
    "timeout": 5,
    "attentionIds": [],
    "deniedTypes": []
  },
  "beforeOfflinePush": {
    "enable": false,
    "timeout": 5,
    "failedContinue": true,
    "deniedTypes": []
  },
  "beforeOnlinePush": {
    "enable": false,
    "timeout": 5,
    "failedContinue": true,
    "deniedTypes": []
  },
  "beforeGroupOnlinePush": {
    "enable": false,
    "timeout": 5,
    "failedContinue": true,
    "deniedTypes": []
  },
  "beforeAddFriend": {
    "enable": false,
    "timeout": 5,
    "failedContinue": true,
    "deniedTypes": []
  },
  "beforeUpdateUserInfo": {
    "enable": false,
    "timeout": 5,
    "failedContinue": true,
    "deniedTypes": []
  },
  "afterUpdateUserInfo": {
    "enable": false,
    "timeout": 5,
    "attentionIds": [],
    "deniedTypes": []
  },
  "beforeCreateGroup": {
    "enable": false,
    "timeout": 5,
    "failedContinue": true,
    "deniedTypes": []
  },
  "afterCreateGroup": {
    "enable": false,
    "timeout": 5,
    "attentionIds": [],
    "deniedTypes": []
  },
  "beforeMemberJoinGroup": {
    "enable": false,
    "timeout": 5,
    "failedContinue": true,
    "deniedTypes": []
  },
  "beforeSetGroupMemberInfo": {
    "enable": false,
    "timeout": 5,
    "failedContinue": true,
    "deniedTypes": []
  },
  "afterSetGroupMemberInfo": {
    "enable": false,
    "timeout": 5,
    "attentionIds": [],
    "deniedTypes": []
  },
  "afterQuitGroup": {
    "enable": false,
    "timeout": 5,
    "attentionIds": [],
    "deniedTypes": []
  },
  "afterKickGroupMember": {
    "enable": false,
    "timeout": 5,
    "attentionIds": [],
    "deniedTypes": []
  },
  "afterDismissGroup": {
    "enable": false,
    "timeout": 5,
    "attentionIds": [],
    "deniedTypes": []
  },
  "beforeApplyJoinGroup": {
    "enable": false,
    "timeout": 5,
    "failedContinue": true,
    "deniedTypes": []
  },
  "afterGroupMsgRead": {
    "enable": false,
    "timeout": 5,
    "attentionIds": [],
    "deniedTypes": []
  },
  "afterSingleMsgRead": {
    "enable": false,
    "timeout": 5,
    "attentionIds": [],
    "deniedTypes": []
  },
  "beforeUserRegister": {
    "enable": false,
    "timeout": 5,
    "failedContinue": true,
    "deniedTypes": []
  },
  "afterUserRegister": {
    "enable": false,
    "timeout": 5,
    "attentionIds": [],
    "deniedTypes": []
  },
  "afterTransferGroupOwner": {
    "enable": false,
    "timeout": 5,
    "attentionIds": [],
    "deniedTypes": []
  },
  "beforeSetFriendRemark": {
    "enable": false,
    "timeout": 5,
    "failedContinue": true,
    "deniedTypes": []
  },
  "afterSetFriendRemark": {
    "enable": false,
    "timeout": 5,
    "attentionIds": [],
    "deniedTypes": []
  },
  "afterGroupMsgRevoke": {
    "enable": false,
    "timeout": 5,
    "attentionIds": [],
    "deniedTypes": []
  },
  "afterJoinGroup": {
    "enable": false,
    "timeout": 5,
    "attentionIds": [],
    "deniedTypes": []
  },
  "beforeInviteUserToGroup": {
    "enable": false,
    "timeout": 5,
    "failedContinue": true,
    "deniedTypes": []
  },
  "afterSetGroupInfo": {
    "enable": false,
    "timeout": 5,
    "attentionIds": [],
    "deniedTypes": []
  },
  "beforeSetGroupInfo": {
    "enable": false,
    "timeout": 5,
    "failedContinue": true,
    "deniedTypes": []
  },
  "afterSetGroupInfoEx": {
    "enable": false,
    "timeout": 5,
    "attentionIds": [],
    "deniedTypes": []
  },
  "beforeSetGroupInfoEx": {
    "enable": false,
    "timeout": 5,
    "failedContinue": true,
    "deniedTypes": []
  },
  "afterRevokeMsg": {
    "enable": false,
    "timeout": 5,
    "attentionIds": [],
    "deniedTypes": []
  },
  "beforeAddBlack": {
    "enable": false,
    "timeout": 5,
    "failedContinue": true,
    "deniedTypes": []
  },
  "afterAddFriend": {
    "enable": false,
    "timeout": 5,
    "attentionIds": [],
    "deniedTypes": []
  },
  "beforeAddFriendAgree": {
    "enable": false,
    "timeout": 5,
    "failedContinue": true,
    "deniedTypes": []
  },
  "afterAddFriendAgree": {
    "enable": false,
    "timeout": 5,
    "attentionIds": [],
    "deniedTypes": []
  },
  "afterDeleteFriend": {
    "enable": false,
    "timeout": 5,
    "attentionIds": [],
    "deniedTypes": []
  },
  "beforeImportFriends": {
    "enable": false,
    "timeout": 5,
    "failedContinue": true,
    "deniedTypes": []
  },
  "afterImportFriends": {
    "enable": false,
    "timeout": 5,
    "attentionIds": [],
    "deniedTypes": []
  },
  "afterRemoveBlack": {
    "enable": false,
    "timeout": 5,
    "attentionIds": [],
    "deniedTypes": []
  },
  "beforeCreateSingleChatConversations": {
    "enable": false,
    "timeout": 5,
    "failedContinue": false,
    "deniedTypes": []
  },
  "afterCreateSingleChatConversations": {
    "enable": false,
    "timeout": 5,
    "attentionIds": [],
    "deniedTypes": []
  },
  "beforeCreateGroupChatConversations": {
    "enable": false,
    "timeout": 5,
    "failedContinue": false,
    "deniedTypes": []
  },
  "afterCreateGroupChatConversations": {
    "enable": false,
    "timeout": 5,
    "attentionIds": [],
    "deniedTypes": []
  },
  "beforeUpdateUserInfoEx": {
    "enable": false,
    "timeout": 5,
    "failedContinue": true,
    "deniedTypes": []
  },
  "afterUpdateUserInfoEx": {
    "enable": false,
    "timeout": 5,
    "attentionIds": [],
    "deniedTypes": []
  }
}
```

### 最小配置示例（仅启用消息回调）

```json
{
  "url": "http://your-webhook-server:8080/callback",
  "beforeSendSingleMsg": {
    "enable": true,
    "timeout": 5,
    "failedContinue": true,
    "deniedTypes": []
  },
  "afterSendSingleMsg": {
    "enable": true,
    "timeout": 5,
    "attentionIds": [],
    "deniedTypes": []
  },
  "beforeSendGroupMsg": {
    "enable": true,
    "timeout": 5,
    "failedContinue": true,
    "deniedTypes": []
  },
  "afterSendGroupMsg": {
    "enable": true,
    "timeout": 5,
    "attentionIds": [],
    "deniedTypes": []
  }
}
```

### 过滤特定消息类型示例

```json
{
  "url": "http://your-webhook-server:8080/callback",
  "beforeSendSingleMsg": {
    "enable": true,
    "timeout": 5,
    "failedContinue": true,
    "deniedTypes": [101, 102]
  }
}
```

### 仅关注特定用户/群组示例

```json
{
  "url": "http://your-webhook-server:8080/callback",
  "afterSendSingleMsg": {
    "enable": true,
    "timeout": 5,
    "attentionIds": ["user001", "user002"],
    "deniedTypes": []
  },
  "afterSendGroupMsg": {
    "enable": true,
    "timeout": 5,
    "attentionIds": ["group001", "group002"],
    "deniedTypes": []
  }
}
```

## 配置说明

### URL 配置

- **格式**: `http://host:port/path` 或 `https://host:port/path`
- **示例**: 
  - `http://127.0.0.1:8080/callback`
  - `http://webhook.example.com:8080/callback`
  - `https://webhook.example.com/callback`

### timeout（超时时间）

- **单位**: 秒
- **建议值**: 5-30 秒
- **说明**: 如果回调服务器在超时时间内没有响应，将根据 `failedContinue` 决定是否继续执行

### failedContinue（失败是否继续）

- **仅适用于**: BeforeConfig 类型的事件
- **true**: 回调失败时继续执行原操作
- **false**: 回调失败时停止执行原操作

### deniedTypes（拒绝的消息类型）

- **类型**: 整数数组
- **说明**: 列表中的消息类型不会触发回调
- **空数组**: 表示所有消息类型都触发回调
- **常用消息类型**:
  - 101: 文本消息
  - 102: 图片消息
  - 103: 语音消息
  - 104: 视频消息
  - 105: 文件消息

### attentionIds（关注ID列表）

- **仅适用于**: AfterConfig 类型的事件
- **类型**: 字符串数组
- **说明**: 
  - 对于消息回调：仅对指定的用户ID或群组ID触发回调
  - 空数组表示所有用户/群组都触发回调
- **示例**: `["user001", "user002", "group001"]`

## 配置存储

### 数据库存储

配置可以存储在 MongoDB 的 `system_configs` 表中：

- **表名**: `system_configs`
- **配置键**: `webhook_config`
- **值类型**: JSON (ValueType = 4)

### 配置优先级

1. **数据库配置**（如果存在且有效）
2. **文件配置**（`config/webhooks.yml`）

如果数据库中没有配置或配置无效（为空、禁用、格式错误等），将自动使用文件配置。

## 配置刷新

- **刷新间隔**: 30 秒（调试模式，生产环境建议改为1小时）
- **自动刷新**: 服务启动后自动开始定时刷新
- **立即生效**: 配置更新后，最多30秒内自动生效（无需重启服务）

## 注意事项

1. **URL 必须有效**: 配置的 URL 必须可访问，否则回调会失败
2. **超时设置**: 建议根据回调服务器的响应时间合理设置超时时间
3. **失败处理**: BeforeConfig 类型的回调建议设置 `failedContinue: true`，避免因回调失败影响正常业务
4. **性能考虑**: 启用过多回调可能影响系统性能，建议按需启用
5. **安全性**: 确保回调服务器有适当的认证机制