企业官网建设流程全解析

Automatisch 集成 ClickUp 触发器指南：Webhook 事件配置与源码实现解析

【免费下载链接】automatischThe open source Zapier alternative. Build workflow automation without spending time and money.项目地址: https://gitcode.com/GitHub_Trending/au/automatisch

本文以 ClickUp 触发器文档 为主体，结合 Automatisch 仓库中 ClickUp 集成模块的源码实现，系统讲解 Automatisch 中 ClickUp 四个触发器（New folders、New lists、New tasks、Updated task）的用途、参数配置方式与底层 Webhook 工作原理，帮助你快速搭建基于 ClickUp 事件的自动化工作流，并理解 Automatisch 触发器从「注册 Webhook」到「事件推送」再到「流程执行」的完整链路。

一、ClickUp 触发器总览

在 Automatisch（开源版 Zapier 替代方案）中，ClickUp 集成共提供 4 个触发器（Trigger），全部属于Webhook 类型，即由 ClickUp 主动推送事件到 Automatisch，而非 Automatisch 定时轮询。这保证了流程触发的实时性。

根据官方文档 triggers.md 的元数据声明，4 个触发器及其功能如下：

从源码结构看，这 4 个触发器在 triggers/index.js 中统一注册导出：

import newFolders from './new-folders/index.js'; import newLists from './new-lists/index.js'; import newTasks from './new-tasks/index.js'; import updatedTask from './updated-task/index.js'; export default [newFolders, newLists, newTasks, updatedTask];

ClickUp 应用本体则在 index.js 中通过defineApp定义，triggers字段即上述数组，同时声明了 API 基础地址https://api.clickup.com/api、OAuth 鉴权文档链接（connection.md）等元信息。

二、触发器通用参数：Workspace / Space / Folder / List 级联选择

4 个触发器在参数设计上高度一致，均遵循「Workspace → Space → Folder → List → Task」的逐级下钻模式。所有参数都由**动态数据源（Dynamic Data）**实时从 ClickUp API 拉取选项，且依赖关系通过dependsOn声明，实现级联刷新。

2.1 各触发器的参数清单

New folders（新文件夹）——2 个参数：

New lists（新列表）——3 个参数，在 New folders 基础上增加：

New tasks（新任务）——5 个参数：

Updated task（任务更新）——5 个参数，其中前 4 个与 New tasks 相同，第 5 个参数不同：

2.2 参数级联背后的动态数据源

上述参数下拉框的选项均来自 dynamic-data 目录下的一组动态数据源，形成一条完整的调用链：

• listWorkspaces：调用GET /v2/team拉取当前账号的所有工作区（list-workspaces/index.js）；
• listSpaces：依赖workspaceId，调用GET /v2/team/{workspaceId}/space拉取空间列表（list-spaces/index.js）；
• listFolders：依赖spaceId，调用GET /v2/space/{spaceId}/folder拉取文件夹列表（list-folders/index.js）；
• listLists：依赖folderId，调用GET /v2/folder/{folderId}/list拉取列表（list-lists/index.js）；
• listTasks：依赖listId，调用GET /v2/list/{listId}/task拉取任务，并通过order_by: created+reverse: true排序、以last_page字段判断是否分页循环（list-tasks/index.js）。

以 New folders 触发器为例，其在参数定义中通过source.type: 'query'、source.name: 'getDynamicData'引用动态数据源，并将上一步选中的参数值以占位符{parameters.workspaceId}传给下一步（new-folders/index.js）。这就是你切换 Workspace 后 Space 下拉框自动刷新的原因。

提示：所有参数都声明了variables: true，意味着这些参数在流程后续步骤中可被当作变量引用。

三、Webhook 型触发器的生命周期：注册 → 监听 → 注销

Automatisch 中的 Webhook 型触发器通过defineTrigger定义，每个触发器都实现 4 个核心生命周期方法。以 ClickUp 触发器为例，这套机制可以完整拆解如下（define-trigger.js 为定义辅助函数）。

3.1 registerHook：向 ClickUp 注册 Webhook

流程启用（Publish）时，Automatisch 会调用registerHook，向 ClickUp API 发送POST /v2/team/{workspaceId}/webhook请求完成订阅。四个触发器的注册逻辑遵循同一模式，payload 随触发器不同而附加不同的事件与作用域参数。以New tasks为例（new-tasks/index.js）：

async registerHook($) { const { workspaceId, spaceId, folderId, listId, taskId } = $.step.parameters; const payload = { name: $.flow.id, // 用流程 ID 作为 Webhook 名称，便于追踪归属 endpoint: $.webhookUrl, // Automatisch 生成的回调地址 events: ['taskCreated'], space_id: spaceId, }; if (folderId) payload.folder_id = folderId; if (listId) payload.list_id = listId; if (taskId) payload.task_id = taskId; const { data } = await $.http.post(`/v2/team/${workspaceId}/webhook`, payload); await $.flow.setRemoteWebhookId(data.id); // 保存远端 Webhook ID，供注销使用 }

各触发器的events字段与作用域参数汇总：

值得注意的是Updated task的events不是固定的，而是取用户选择的whatChanged参数值（taskStatusUpdated、taskAssigneeUpdated、taskPriorityUpdated、taskTagUpdated），未选择时回退为通用事件taskUpdated（updated-task/index.js）。这实现了「仅当任务状态变更时才触发」这类精细化订阅。

3.2 run：接收事件并推送数据

当 ClickUp 将事件 POST 到 Automatisch 的回调地址后，触发器调用run方法。该方法把请求体包装为数据项并通过$.pushTriggerItem推入流程执行。以 New folders 为例（new-folders/index.js）：

async run($) { const dataItem = { raw: $.request.body, // ClickUp 推送的原始事件体 meta: { internalId: $.request.body.folder_id, // 去重标识：文件夹 ID }, }; $.pushTriggerItem(dataItem); }

各触发器internalId的去重策略：

这里internalId用于事件去重：前三个触发器以被创建实体的 ID 作为唯一标识，即使 ClickUp 重复推送同一事件也不会重复执行流程；而 Updated task 因同一任务可能多次更新，故每次生成随机 UUID，确保每次更新都触发流程。

3.3 unregisterHook：流程停用后清理订阅

流程停用（Unpublish）或删除时，Automatik 调用unregisterHook，通过DELETE /v2/webhook/{remoteWebhookId}删除 ClickUp 端的 Webhook 订阅（如 new-lists/index.js），避免残留无效订阅消耗 ClickUp 配额。

3.4 testRun：测试阶段的模拟事件

在 Automatisch 编辑器中点击「Test step」时，触发器不会真的等待 ClickUp 事件，而是调用testRun推送一份模拟事件数据。例如 New tasks 的测试数据为：

{ event: 'taskCreated', task_id: '86enn7pg7', webhook_id: Crypto.randomUUID(), history_items: [], }

这样可以在不产生真实 ClickUp 操作的情况下验证后续步骤的字段映射是否正确。

四、使用场景与实战建议

结合上文参数与事件机制，4 个触发器可覆盖 ClickUp 项目管理中的典型自动化场景：

1. New folders：某个空间新增文件夹时，自动创建对应的文档目录、通知团队成员；
2. New lists：某个文件夹下新增列表（如新的冲刺 Sprint）时，自动初始化看板配置或创建关联资源；
3. New tasks：新任务创建时自动分配负责人、设置默认标签、发送 Slack/Discord 通知；
4. Updated task：配合What Changed?参数实现精细化监听——例如仅当任务状态变更为完成时触发通知，或任务优先级被调整时同步到外部系统。

使用要点

• 触发器的前置条件：使用任何 ClickUp 触发器前，需先在 Automatisch 中创建 ClickUp 连接（OAuth 授权），完整步骤见 ClickUp 连接指南。
• 精确订阅 vs 全量订阅：层级参数（Space / Folder / List）全部可选，越不指定，Webhook 监听的粒度越粗（事件量越大）；建议尽量下钻到最小作用域，减少无关事件流量。
• Updated task 的"What Changed?"：该参数直接映射为 ClickUp Webhook 的事件类型，是实现"只在特定变更发生时触发"的关键，选择后流程仅在对应事件推送时启动。
• 与动作搭配：触发器只是流程的起点，可继续在 Automatisch 编辑器中追加 ClickUp 动作（如 Create task、Find task by id 等）或其他应用的步骤，构建完整的自动化链路。

五、实现要点速查

• 应用注册：packages/backend/src/apps/clickup/index.js —— 定义应用名、API 地址、鉴权、触发器与动作的装配；
• 触发器集合：packages/backend/src/apps/clickup/triggers/index.js —— 4 个触发器的统一出口；
• 单个触发器实现：new-folders、new-lists、new-tasks、updated-task 四个index.js；
• 动态数据源：dynamic-data/index.js 目录下的 5 个index.js负责级联下拉选项的实时拉取；
• 官方文档：triggers.md（触发器清单）、connection.md（连接配置）、actions.md（配套动作）。

总结来说，Automatisch 的 ClickUp 触发器以 Webhook 订阅为基石，通过「动态数据源 + 级联参数 + 事件类型映射」实现了高度灵活的实时触发能力。无论是新建文件夹、列表、任务，还是对任务更新的精细化监听，都可以通过编辑器中寥寥几步配置完成，而其背后的注册、去重、注销机制则完全由 Automatisch 托管，无需关心 Webhook 的底层管理细节。

【免费下载链接】automatischThe open source Zapier alternative. Build workflow automation without spending time and money.项目地址: https://gitcode.com/GitHub_Trending/au/automatisch