feat: add Unified Webhook Mode support and update related documentation

Author: Soulter

.vitepress/config.mjs

@@ -170,6 +170,7 @@ export default defineConfig({
               { text: "知识库", link: "/knowledge-base" },
               { text: "自定义规则", link: "/custom-rules" },
               { text: "Agent 执行器", link: "/agent-runner" },
+              { text: "统一 Webhook 模式", link: "/unified-webhook" },
               { text: "沙箱化代码执行器(beta)", link: "/code-interpreter" },
             ],
           },
@@ -389,6 +390,7 @@ export default defineConfig({
               { text: "Knowledge Base", link: "/knowledge-base" },
               { text: "Custom Rules", link: "/custom-rules" },
               { text: "Agent Runner", link: "/agent-runner" },
+              { text: "Unified Webhook Mode", link: "/unified-webhook" },
               { text: "Sandboxed Code Interpreter (beta)", link: "/code-interpreter" },
             ],
           },

en/deploy/platform/slack.md

@@ -51,17 +51,29 @@ Slack supports two connection methods: `Webhook` and `Socket`. If you don't have
 
 ## Start the Platform Adapter
 
-The configuration is now complete. If you're using Socket mode, simply click the Save button in the bottom right corner of the configuration. If you're using Webhook mode, you can also configure the Slack Webhook Host, Slack Webhook Port, and Slack Webhook Path according to your needs. Generally, using the default values is sufficient.
+The configuration is now complete. If you're using Socket mode, simply click the Save button in the bottom right corner of the configuration.
+
+If you're using Webhook mode, please keep `Unified Webhook Mode (unified_webhook_mode)` enabled.
+
+> [!TIP]
+> Before v4.8.0, there is no `Unified Webhook Mode`. You need to fill in the following configuration items:
+> Slack Webhook Host, Slack Webhook Port, and Slack Webhook Path
 
 
 ## Enable Event Subscriptions
 
 After successfully creating the platform adapter, return to the Slack settings. In the Event Subscriptions page on the left sidebar, click Enable Events to enable event reception.
 
-If you're using Webhook mode, enter `https://your-domain/astrbot-slack-webhook/callback` in the `Request URL` field that appears.
+If you're using Webhook mode:
+
+- If `Unified Webhook Mode` is enabled, after clicking save, AstrBot will automatically generate a unique Webhook callback URL for you. You can find it in the logs or on the bot card in the WebUI's Bots page. Enter this URL in the `Request URL` field.
+
+![unified_webhook](/source/images/use/unified-webhook.png)
+
+- If `Unified Webhook Mode` is not enabled, enter `https://your-domain/astrbot-slack-webhook/callback` in the `Request URL` field.
 
 > [!TIP]
-> In Webhook mode, you need to first set up your domain with your DNS provider, then use reverse proxy software to proxy the Slack Webhook Port you configured in the previous step to your domain. Alternatively, you can use Cloudflare Tunnel. For detailed tutorials, please refer to online resources; this tutorial will not cover these in detail.
+> In Webhook mode, you need to first set up your domain with your DNS provider, then use reverse proxy software to forward requests to port `6185` on the AstrBot server (if Unified Webhook Mode is enabled) or the port specified in your configuration (if Unified Webhook Mode is not enabled). Alternatively, you can use Cloudflare Tunnel. For detailed tutorials, please refer to online resources; this tutorial will not cover these in detail.
 
 After enabling, under Subscribe to bot events below, click Add Bot User Event and add the following events:
 

en/deploy/platform/wecom.md

@@ -35,11 +35,17 @@ AstrBot 支持接入企业微信应用和微信客服。
 
 如果您之前使用过微信客服机器人，那么在 `开发配置` 中直接找到 `回调配置`，点击修改。
 
-回调 URL 填写： `http://你的带公网地址的服务器ip:6195/callback/command`
+点击下方的两个随机获取，得到 `Token` 和 `EncodingAESKey`，复制到 AstrBot 配置的 `token` 和 `encoding_aes_key` 处。请保持 `统一 Webhook 模式 (unified_webhook_mode)` 为开启状态。然后点击保存配置，等待适配器加载完成。
 
-> 请注意放行端口
+回调 URL 填写：
 
-点击下方的两个随机获取，得到 `Token` 和 `EncodingAESKey`，复制到 AstrBot 配置的 `token` 和 `encoding_aes_key` 处，然后点击保存配置，等待适配器加载完成。
+- 如果开启了 `统一 Webhook 模式`，点击保存之后，AstrBot 将会自动为你生成唯一的 Webhook 回调链接，你可以在日志中或者 WebUI 的机器人页的卡片上找到，将该链接填入回调 URL 处。
+
+![unified_webhook](/source/images/use/unified-webhook.png)
+
+- 如果没有开启 `统一 Webhook 模式`，填写 `http://你的带公网地址的服务器ip:6195/callback/command`。
+
+> 请注意放行端口。如果开启了统一 Webhook 模式，需要将请求转发到 AstrBot 所在服务器的 `6185` 端口；如果没有开启，则转发到配置指定的端口（默认 `6195`）。
 
 回到微信客服 `回调配置`，点击 `完成`。如果一切无误，将会显示 `已完成`（否则会显示类似 `openapi 回调不通过` 类似的文本）。
 
@@ -81,13 +87,19 @@ AstrBot 支持接入企业微信应用和微信客服。
 
 ![image](/source/images/wecom/image-9.png)
 
-在 URL 处填入 `http://你的带公网地址的服务器ip:6195/callback/command`
+并且点击下方的两个随机获取，得到 `Token` 和 `EncodingAESKey`，复制到 AstrBot 配置的 `token` 和 `encoding_aes_key` 处。建议保持 `统一 Webhook 模式 (unified_webhook_mode)` 为开启状态。
+
+现在应该已经填完 AstrBot 连接到企业微信的所有配置项。点击 AstrBot 配置页右下角保存，等待 AstrBot 重启。
 
-> 请注意放行端口
+在 URL 处填入回调地址：
 
-并且点击下方的两个随机获取，得到 `Token` 和 `EncodingAESKey`，复制到 AstrBot 配置的 `token` 和 `encoding_aes_key` 处。
+- 如果开启了 `统一 Webhook 模式`，点击保存之后，AstrBot 将会自动为你生成唯一的 Webhook 回调链接，你可以在日志中或者 WebUI 的机器人页的卡片上找到，将该链接填入 URL 处。
 
-现在应该已经填完 AstrBot 连接到企业微信的所有配置项。点击 AstrBot 配置页右下角保存，等待 AstrBot 重启。
+![unified_webhook](/source/images/use/unified-webhook.png)
+
+- 如果没有开启 `统一 Webhook 模式`，填入 `http://你的带公网地址的服务器ip:6195/callback/command`。
+
+> 请注意放行端口。如果开启了统一 Webhook 模式，需要将请求转发到 AstrBot 所在服务器的 `6185` 端口；如果没有开启，则转发到配置指定的端口（默认 `6195`）。
 
 接下来配置企业可信 IP。
 

en/deploy/platform/wecom_ai_bot.md

@@ -22,11 +22,17 @@ AstrBot 在 v4.3.5 版本开始支持接入企业微信智能机器人平台。
 
 ![新增适配器](/source/images/wecom_ai_bot/image-2.png)
 
-2. 在弹出的配置项中将 `企业微信智能机器人的名字`、`token`、`encoding_aes_key` 从上一步创建智能机器人时填写的值复制粘贴到对应的输入框中。ID 可以随意填写，用于区分不同的消息平台实例。`port` 默认为 `6198`，可以根据需要修改，但请确保该端口未被占用。点击 `保存`。
+2. 在弹出的配置项中将 `企业微信智能机器人的名字`、`token`、`encoding_aes_key` 从上一步创建智能机器人时填写的值复制粘贴到对应的输入框中。ID 可以随意填写，用于区分不同的消息平台实例。`port` 默认为 `6198`，可以根据需要修改，但请确保该端口未被占用。请保持 `统一 Webhook 模式 (unified_webhook_mode)` 为开启状态。点击 `保存`。
 
-3. 回到企业微信智能机器人创建页面，填写 `URL` 为 `http://IP:port/webhook/wecom-ai-bot`，其中 `IP` 替换为你的 AstrBot 服务器的公网 IP 地址，`port` 替换为上一步填写的端口号。
+3. 回到企业微信智能机器人创建页面，填写 `URL`：
 
-> 建议有能力的用户自行配置域名和反向代理，并使用 HTTPS 协议。如果没有域名，也可以使用 [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/tunnel-guide/)。
+   - 如果开启了 `统一 Webhook 模式`，点击保存之后，AstrBot 将会自动为你生成唯一的 Webhook 回调链接，你可以在日志中或者 WebUI 的机器人页的卡片上找到，将该链接填入 `URL` 处。
+
+   ![unified_webhook](/source/images/use/unified-webhook.png)
+
+   - 如果没有开启 `统一 Webhook 模式`，填写 `http://IP:port/webhook/wecom-ai-bot`，其中 `IP` 替换为你的 AstrBot 服务器的公网 IP 地址，`port` 替换为上一步填写的端口号。
+
+> 建议有能力的用户自行配置域名和反向代理，将请求转发到 AstrBot 所在服务器的 `6185` 端口（如果开启了统一 Webhook 模式）或配置指定的端口（如果没有开启统一 Webhook 模式），并使用 HTTPS 协议。如果没有域名，也可以使用 [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/tunnel-guide/)。
 
 4. 点击 `创建` 按钮，如果一切无误，将进入智能机器人详情页面。如果报错 `服务没有正确响应，请确认后重试`，请检查 AstrBot 的配置、服务器防火墙端口放行规则等。
 

en/deploy/platform/weixin-official-account.md

@@ -36,15 +36,23 @@ AstrBot 支持接入微信公众平台（版本 >= v3.5.8），并以微信公
 找到下方的服务器配置，然后点击修改配置。
 
 
-`URL` 请填入 `http://你的域名/callback/command`
-
-> 注意⚠️：仅支持 80 或者 443 端口。您可能需要购买域名，然后反向代理 6194 端口的流量，或者将 6194 端口改成 80 端口（注意服务器需要没有软件在占用 80 端口）。
-
 `Token` 由自己填写，请随意填写一个字符串，长度 3-32 位。并同样填入 AstrBot 配置的 `token` 处（一定要相同）。
 
 `EncodingAESKey` 请点击随机生成，然后复制到 AstrBot 配置的 `encoding_aes_key` 处。
 
-现在应该已经填完 AstrBot 连接到企业微信的所有配置项。点击 AstrBot 配置页右下角保存，等待 AstrBot 重启。
+建议保持 `统一 Webhook 模式 (unified_webhook_mode)` 为开启状态。
+
+现在应该已经填完 AstrBot 连接到微信公众平台的所有配置项。点击 AstrBot 配置页右下角保存，等待 AstrBot 重启。
+
+`URL` 填写：
+
+- 如果开启了 `统一 Webhook 模式`，点击保存之后，AstrBot 将会自动为你生成唯一的 Webhook 回调链接，你可以在日志中或者 WebUI 的机器人页的卡片上找到，将该链接填入 URL 处。
+
+![unified_webhook](/source/images/use/unified-webhook.png)
+
+- 如果没有开启 `统一 Webhook 模式`，请填入 `http://你的域名/callback/command`。
+
+> 注意⚠️：仅支持 80 或者 443 端口。您可能需要购买域名，然后反向代理流量到 AstrBot 所在服务器的 `6185` 端口（如果开启了统一 Webhook 模式）或 `6194` 端口（如果没有开启统一 Webhook 模式），或者将端口改成 80 端口（注意服务器需要没有软件在占用 80 端口）。
 
 消息加解密方式请选中 `安全模式`。
 

en/use/unified-webhook.md

@@ -0,0 +1,28 @@
+# Unified Webhook Mode
+
+Starting from v4.8.0, AstrBot supports Unified Webhook Mode (unified_webhook_mode). When this mode is enabled, all platform adapters that support it will use the same Webhook callback endpoint, simplifying reverse proxy and domain configuration. You no longer need to configure separate ports, domains, and reverse proxies for each bot adapter.
+
+Platform adapters that support Unified Webhook Mode include:
+
+- Slack Webhook Mode
+- WeChat Official Account
+- WeCom Application
+- WeCom AI Bot
+- WeChat Customer Service Bot
+- QQ Official Bot Webhook Mode
+- ...
+
+## How to Use Unified Webhook Mode
+
+1. Have a domain (e.g., example.com) and a server with a public IP
+2. Configure DNS resolution (e.g., astrbot.example.com)
+3. Configure reverse proxy to forward requests from port 80 or 443 of your domain to AstrBot's WebUI port (default is 6185)
+4. Go to AstrBot's `Configuration` page, click `System`, and set the `Externally Reachable Callback URL` to your configured URL (e.g., https://astrbot.example.com). Click save and wait for restart.
+
+When configuring each platform adapter afterwards, enable `Unified Webhook Mode (unified_webhook_mode)`.
+
+![unified_webhook](/source/images/use/unified-webhook-config.png)
+
+Once this mode is enabled, AstrBot will generate a unique Webhook callback URL for you. You just need to fill this URL into each platform's callback address field.
+
+![unified_webhook](/source/images/use/unified-webhook.png)

source/images/use/unified-webhook-config.png

@@ -1,14 +1,14 @@
 
 # 通过 QQ官方机器人 接入 QQ (Webhook)
 
-## 申请一个机器人
-
 > [!WARNING]
 >
 > 1. 截至目前，QQ 官方机器人需要设置 IP 白名单。
 > 2. 支持群聊、私聊、频道聊天、频道私聊。
 >
-> 需要一台带有公网 IP 的服务器和域名（如果没备案，需要服务器在海外或者中国港澳台）
+> **需要**一台带有公网 IP 的服务器和域名（如果没备案，需要服务器在海外或者中国港澳台地区）
+
+## 申请一个机器人
 
 首先，打开 [QQ官方机器人](https://q.qq.com) 并登录。
 
@@ -51,16 +51,26 @@
 - 启用(enable): 勾选。
 - appid: QQ 官方机器人中获取的 appid。
 - secret: QQ 官方机器人中获取的 secret。
+- 统一 Webhook 模式 (unified_webhook_mode): 保持开启。
 
 点击 `保存`。
 
+## 反向代理
+
+保存之后，请根据你的服务器环境，配置域名 DNS 解析和反向代理，将请求转发到 AstrBot 所在服务器的 `6185` 端口 (如果没有开启统一 Webhook 模式，将请求转发到上一步配置指定的端口)。
+
 ## 设置回调地址
 
-在 `开发->回调配置` 处，配置回调地址。这需要你拥有一个公网 IP 服务器和域名。
+在 `开发->回调配置` 处，配置回调地址。
+
+上一步点击保存之后，AstrBot 将会自动为你生成唯一的 Webhook 回调链接，你可以在日志中或者 WebUI 的机器人页的卡片上找到。
+
+![unified_webhook](/source/images/use/unified-webhook.png)
 
-请求地址填写 `<你的域名>/astrbot-qo-webhook/callback`
+将请求地址填写为该地址。
 
-你的域名应当通过 `Caddy`, `Nginx`, `Apache` 等 Web 服务器反向代理来自 AstrBot 暴露的 `6196` 端口的流量。
+> [!TIP]
+> v4.8.0 之前没有 `统一 Webhook 模式`，则请求地址填写 `<你的域名>/astrbot-qo-webhook/callback`。
 
 填写好之后，添加事件，四个事件类型都全选：单聊事件、群事件、频道事件等，如下图。
 

source/images/use/unified-webhook.png

@@ -51,17 +51,28 @@ Slack 支持两种接入方式：`Webhook` 与 `Socket`。如果您没有公网
 
 ## 启动平台适配器
 
-现在，配置已经完成。如果您使用的是 Socket 模式，那么直接点击配置的右下角的保存按钮即可。如果您使用的是 Webhook 模式，还可以按照您的需要来设置配置中的 Slack Webhook Host、Slack Webhook Port 和 Slack Webhook Path。一般来说使用默认值已经足够。
+现在，配置已经完成。如果您使用的是 Socket 模式，那么直接点击配置的右下角的保存按钮即可。
 
+如果您使用的是 Webhook 模式，请保持 `统一 Webhook 模式 (unified_webhook_mode)` 为开启状态。
+
+> [!TIP]
+> v4.8.0 之前没有 `统一 Webhook 模式`，请填写以下配置项：
+> Slack Webhook Host、Slack Webhook Port 和 Slack Webhook Path
 
 ## 开启事件接收
 
 新建平台适配器成功后，返回到 Slack 设置，在左边栏 Event Subscriptions 页下，点击 Enable Events 启用事件接收。
 
-如果您使用的是 Webhook 模式，请在在出现的 `Request URL` 输入框中输入 `https://您的域名/astrbot-slack-webhook/callback`。
+如果您使用的是 Webhook 模式：
+
+- 如果开启了 `统一 Webhook 模式`，点击保存之后，AstrBot 将会自动为你生成唯一的 Webhook 回调链接，你可以在日志中或者 WebUI 的机器人页的卡片上找到，将该链接填入 `Request URL` 输入框中。
+
+![unified_webhook](/source/images/use/unified-webhook.png)
+
+- 如果没有开启 `统一 Webhook 模式`，请在 `Request URL` 输入框中输入 `https://您的域名/astrbot-slack-webhook/callback`。
 
 > [!TIP]
-> Webhook 模式下，您需要先在 DNS 服务商处设置好域名，然后使用反向代理软件将上一步中填写的 Slack Webhook Port 反向代理到您设置的域名。或者您可以使用 Cloudflare Tunnel。具体教程请参考网络资源，本教程不赘述。
+> Webhook 模式下，您需要先在 DNS 服务商处设置好域名，然后使用反向代理软件将请求转发到 AstrBot 所在服务器的 `6185` 端口（如果开启了统一 Webhook 模式）或配置指定的端口（如果没有开启统一 Webhook 模式）。或者您可以使用 Cloudflare Tunnel。具体教程请参考网络资源，本教程不赘述。
 
 启用后，在下方的 Subscribe to bot events 处，点击 Add Bot User Event，添加如下事件：