Activepieces 怎么配置 Slack OAuth2 应用的事件订阅与 Webhook Secret？

Slack 这类应用只允许每个 OAuth2 应用绑定一个 Webhook，无法由 Activepieces 自动代配，必须在 Slack 开发者后台手动完成事件订阅和签名密钥的配置。本文对应 docs/install/configure-operate/setup-app-webhooks.mdx 中 Slack 章节的完整操作：在 Slack 开发者平台配置 Webhook URL、事件订阅和 Socket Mode 开关，并在 Activepieces 侧写入 AP_APP_WEBHOOK_SECRETS 环境变量，使 Slack 的触发器能正常接收事件。

配置 Webhook Secret

Slack 在 OAuth 设置的 Basic Information 部分提供一个 "Signing Secret"，Activepieces 用它校验事件来源。操作顺序是：

1. 打开 Slack OAuth 设置，进入 "Basic Information" 区域。
2. 复制 "Signing Secret" 并妥善保存。
3. 在 Activepieces 的运行环境中设置如下环境变量，把 SIGNING_SECRET 替换为第 2 步复制到的值：

AP_APP_WEBHOOK_SECRETS={"@activepieces/piece-slack": {"webhookSecret": "SIGNING_SECRET"}}

4. 重启 Activepieces 应用实例使配置生效。

这个变量是一个 JSON 映射，键是 piece 包名 @activepieces/piece-slack，值是包含 webhookSecret 字段的对象。

配置 Webhook URL 与事件订阅

在 Slack OAuth2 开发者平台的 Event Subscription 设置中完成订阅：

1. 将 Request URL 设为以下格式，YOUR_AP_INSTANCE 替换为你的 Activepieces 实例域名：

   https://YOUR_AP_INSTANCE/api/v1/app-events/slack
   

2. 将以下事件添加到应用：

   • message.channels
   • reaction_added
   • message.im
   • message.groups
   • message.mpim
   • app_mention
   • channel_created
   • reaction_removed
   • star_added
   • team_join
   • emoji_changed

3. 连接 Slack 时使用你的 OAuth2 凭据；在平台版（platform plans）中也可以从管理控制台直接更新 OAuth2 应用信息。

关闭 Socket Mode。 在 Slack 应用的 Settings → Socket Mode 中把它关掉。Socket Mode 开启时，Slack 通过 WebSocket 推送事件，根本不会向 Request URL（https://YOUR_AP_INSTANCE/api/v1/app-events/slack）发送 POST 请求，触发器会静默地永远不触发——这是本文文档明确列出的最常见故障点。

可选：配置 Interactivity & Shortcuts

只有当你要使用 "New Modal Interaction" 触发器，或 "Request Approval"/"Request Action" 这类动作（它们的按钮通过该 URL 恢复流程）时才需要这一步：

1. 进入 Slack OAuth2 开发者平台的 Interactivity & Shortcuts 设置。
2. 开启 interactivity。
3. 把 Request URL 设置为与上文相同的地址：https://YOUR_AP_INSTANCE/api/v1/app-events/slack。

结果验证与限制

配置完成后的判断标准是：Slack 在事件发生时能向 /api/v1/app-events/slack 发出 POST 请求，并且 Activepieces 侧的 Slack 触发器被触发。如果 URL 已经正确填写但触发器从不触发，按文档先检查 Socket Mode 是否仍为开启状态；如果事件被接收但校验失败，检查 AP_APP_WEBHOOK_SECRETS 中的值是否与 Slack "Basic Information" 里的 "Signing Secret" 完全一致，以及修改后是否已重启应用实例。

需要注意的是：Slack 每个 OAuth2 应用只支持一个 Webhook，所以上述 URL 是事件订阅、interactivity 共用的同一条路径，不能为不同目的配置多个地址；AP_APP_WEBHOOK_SECRETS 属于环境变量级配置，修改后必须重启实例才生效。