itom-group/open-im-server-deploy

Fork 0

Files

kim.dev.6789 e50142a3b9 复制项目

2026-01-14 22:16:44 +08:00

15 KiB

Raw Blame History

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 配置示例

完整配置示例

{
  "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": []
  }
}

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

{
  "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": []
  }
}

过滤特定消息类型示例

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

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

{
  "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)

配置优先级

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

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

配置刷新

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

注意事项

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

15 KiB Raw Blame History Unescape Escape