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 个触发器及其功能如下触发器名称触发时机对应 ClickUp 事件New folders新建文件夹Folder时触发folderCreatedNew lists新建列表List时触发listCreatedNew tasks新建任务Task时触发taskCreatedUpdated task任务被更新时触发taskUpdated等从源码结构看这 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 个参数参数是否必填说明Workspace是要监听的 ClickUp 工作区TeamSpace否限定监听某个空间不选则监听整个工作区New lists新列表——3 个参数在 New folders 基础上增加参数是否必填说明Workspace是工作区Space否空间Folder否文件夹不选则监听该空间下的所有文件夹New tasks新任务——5 个参数参数是否必填说明Workspace是工作区Space否空间Folder否文件夹List否列表不选则监听该文件夹下所有列表Task否可选指定一个任务用于确定流程何时激活选中后仅该任务的子任务subtasks会触发流程Updated task任务更新——5 个参数其中前 4 个与 New tasks 相同第 5 个参数不同参数是否必填说明Workspace是工作区Space否空间Folder否文件夹List否列表What Changed?否指定「何种变更」才触发可选值为 Status状态变更、Assignee Added新增负责人、Priority优先级变更、Tag Added新增标签2.2 参数级联背后的动态数据源上述参数下拉框的选项均来自 dynamic-data 目录下的一组动态数据源形成一条完整的调用链listWorkspaces调用GET /v2/team拉取当前账号的所有工作区list-workspaces/index.jslistSpaces依赖workspaceId调用GET /v2/team/{workspaceId}/space拉取空间列表list-spaces/index.jslistFolders依赖spaceId调用GET /v2/space/{spaceId}/folder拉取文件夹列表list-folders/index.jslistLists依赖folderId调用GET /v2/folder/{folderId}/list拉取列表list-lists/index.jslistTasks依赖listId调用GET /v2/list/{listId}/task拉取任务并通过order_by: createdreverse: 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.jsasync 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字段与作用域参数汇总触发器events 字段附加作用域参数New folders[folderCreated]可选space_idnew-folders/index.jsNew lists[listCreated]space_id必带 可选folder_idnew-lists/index.jsNew tasks[taskCreated]space_id 可选folder_id/list_id/task_idUpdated task[whatChanged || taskUpdated]space_id 可选folder_id/list_id值得注意的是Updated task的events不是固定的而是取用户选择的whatChanged参数值taskStatusUpdated、taskAssigneeUpdated、taskPriorityUpdated、taskTagUpdated未选择时回退为通用事件taskUpdatedupdated-task/index.js。这实现了「仅当任务状态变更时才触发」这类精细化订阅。3.2 run接收事件并推送数据当 ClickUp 将事件 POST 到 Automatisch 的回调地址后触发器调用run方法。该方法把请求体包装为数据项并通过$.pushTriggerItem推入流程执行。以 New folders 为例new-folders/index.jsasync run($) { const dataItem { raw: $.request.body, // ClickUp 推送的原始事件体 meta: { internalId: $.request.body.folder_id, // 去重标识文件夹 ID }, }; $.pushTriggerItem(dataItem); }各触发器internalId的去重策略触发器internalId 来源New folders$.request.body.folder_idNew lists$.request.body.list_idNew tasks$.request.body.task_idUpdated taskCrypto.randomUUID()每次事件都视为新数据不按任务去重这里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 项目管理中的典型自动化场景New folders某个空间新增文件夹时自动创建对应的文档目录、通知团队成员New lists某个文件夹下新增列表如新的冲刺 Sprint时自动初始化看板配置或创建关联资源New tasks新任务创建时自动分配负责人、设置默认标签、发送 Slack/Discord 通知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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考