ToolJet 工作流触发机制完全指南Webhook 与手动触发配置详解【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet导读在 ToolJet 中工作流Workflow是独立于前端应用的自动化编排单元而触发器Triggers则是让工作流真正跑起来的入口。本文基于 ToolJet 2.50.0-LTS 官方文档系统讲解工作流的两种触发方式——Webhook 触发与手动触发涵盖触发器的创建流程、API 端点格式、鉴权方式、参数传递、限流限制等完整配置细节并结合仓库源码server/src/modules/workflows与端到端测试workflow-webhook.spec.ts深入剖析其底层实现原理帮助你从会用进阶到懂原理。触发器概述触发器Triggers用于执行一个工作流。目前ToolJet 支持两种类型的触发器触发器类型触发方式适用场景Webhooks通过 HTTP 请求触发外部系统集成、CI/CD、跨应用调用Manual从 ToolJet 应用中手动运行在 App Builder 中按需执行类似数据源查询两种触发器的核心差异在于谁来发起调用Webhook 由外部系统通过 HTTP 请求发起手动触发则是在 ToolJet 应用内部由用户点击或事件处理器发起。从源码结构看Webhook 触发由独立的后端控制器WorkflowWebhooksController处理而手动触发在查询面板Query Panel中以Run Workflow静态数据源的形式出现见 frontend/src/AppBuilder/QueryManager/constants.js。Webhook 触发器Webhook 触发器允许你在收到 webhook 请求时运行工作流。你可以在Triggers标签页中配置 webhook 触发器每个工作流的 webhook URL 都是唯一的。创建 Webhook 触发器1. 打开 Triggers 标签页点击左侧面板中的Triggers选项打开 Triggers 标签页。2. 选择 Webhooks在 Triggers 标签页中点击Webhooks选项进入 Webhook 配置界面。3. 启用 Webhook 触发器默认情况下webhook 触发器是禁用状态。需要拨动开关将其启用启用后才能获取到可用的端点 URL 与 API Token。4. 选择环境Environment启用后你可以选择Environment环境来获取对应环境的 webhook 端点 URL。例如选择Production生产环境后可点击Copy URL或Copy as cURL复制的端点将用于触发Production环境的对应版本。这一设计背后对应了 ToolJet 的多环境版本机制工作流本质上是应用的一种类型APP_TYPES.WORKFLOW其版本与环境来自 apps/versions 模块见 server/src/modules/workflows/AGENTS.md。因此同一个 webhook 端点通过environment查询参数即可路由到指定环境的版本。5. 获取端点 URL 与 API Token在Endpoint字段中可以找到 API 端点 URL。你可以使用该 URL 发送POST 请求来触发工作流。点击Copy按钮可将 URL 复制到剪贴板从下拉菜单中可选择Copy URL或Copy as cURL。其中Copy as cURL会以 cURL 命令形式复制 URL并包含 API Token 和环境信息。端点 URL 的示例格式如下http://{TOOLJET_HOST}/api/v2/webhooks/workflows/:id/trigger对应的后端路由在 workflow-webhooks.controller.ts 中定义控制器挂在version: 2、路径webhooks下并通过Post(workflows/:id/trigger)暴露触发端点且该端点由FEATURE_KEY.WEBHOOK_TRIGGER_WORKFLOW特性守卫保护。API Token用于认证请求。你可以在API Token字段中找到它点击Copy按钮即可将其复制到剪贴板。:::info 认证说明 目前 webhook强制要求认证。请在Authorization请求头中使用 Bearer token 进行认证。格式Authorization: Bearer secret_token示例Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...:::6. 配置工作流参数Parameters参数可以通过Parameters字段传递给工作流。参数key和其type类型在Parameters字段中指定。例如想要通过 webhook 触发器向工作流传递name和age参数可以按如下方式设置 Parameters 字段name: string, age: number声明参数时须指定数据类型。测试用例证实当传入的参数类型与声明不符时例如声明为string却传入数字2服务端会返回400及错误消息name has incorrect datatype当声明了参数但请求未携带时则返回400及Params - name is missing见 workflow-webhook.spec.ts。7. 测试 Webhook 触发器Test JSON parameters字段可用于测试 webhook 触发器。你可以在其中输入参数值并点击Run按钮来测试 webhook 触发器工作流将使用Test JSON parameters字段中指定的参数值执行。{ name: John Doe, age: 30 }这些参数可以在工作流中通过startTrigger.params访问。测试用例中一个 RunJS 查询节点即通过return startTrigger.params.name读取 webhook 传入的参数值并将结果节点返回该值见 workflow-webhook.spec.ts。调用示例结合官方文档的端点格式与测试用例中的调用方式一个完整的 webhook 触发请求示例如下curl -X POST \ http://{TOOLJET_HOST}/api/v2/webhooks/workflows/:id/trigger?environmentproduction \ -H Authorization: Bearer secret_token \ -H Content-Type: application/json \ -d { name: John Doe, age: 30 }其中:id为工作流的唯一标识可替换为工作流名称trigger-async端点支持idOrNameenvironment查询参数用于指定目标环境如development、production传入无效环境会返回404及Invalid environment请求体为 JSON 格式的参数对象与服务端声明的webhookParams逐一校验。Webhook 触发器的使用限制Webhook 触发器的使用存在一些可配置的限制根据许可证的不同可以在实例级别和工作区级别进行配置每月执行次数每天执行次数并行执行次数每个工作流的执行时长其中限制并行执行次数可使用以下环境变量环境变量值说明WEBHOOK_THROTTLE_TTL60000webhook 请求存活的毫秒数时间窗口WEBHOOK_THROTTLE_LIMIT100在 TTL 窗口内将被限流的最大请求数这两个环境变量在 module.ts 中通过ThrottlerModule.forRootAsync注入ttl取WEBHOOK_THROTTLE_TTL默认 60000limit取WEBHOOK_THROTTLE_LIMIT默认 100。这意味着默认配置下每个时间窗口60 秒内最多允许 100 次请求超出部分将被限流。:::tip 白名单 API 端点 对于虚拟私有云VPC环境建议仅放行{TOOLJET_HOST}/api/v2/workflows/*端点。 :::从限流测试可以看出限流行为由 ThrottlerModule 在应用创建时读取环境变量决定全局生效而非按工作流隔离当窗口内请求数超过限制时服务端返回429及ThrottlerException: Too Many Requests见 workflow-webhook.spec.ts。Webhook 的其他端点能力除了文档重点介绍的同步触发端点外从 workflow-webhooks.controller.ts 可以看出Webhook 控制器还暴露了以下端点方法路径说明POSTwebhooks/workflows/:idOrName/trigger-async异步触发工作流支持按名称idOrName调用GETwebhooks/workflows/:idOrName/status/:executionId查询指定执行execution的状态SSEwebhooks/workflows/:idOrName/execution/:executionId/stream以 Server-Sent Events 方式实时流式获取执行结果PATCHwebhooks/workflows/:id更新工作流的 webhook 配置其中trigger-async、status与stream端点共同构成异步触发与执行跟踪的完整链路适合耗时较长的工作流场景。手动触发器手动触发器可用于从 ToolJet 应用中手动运行工作流。手动触发的工作方式与数据源查询queries类似你可以从查询面板Query Panel为应用添加一个触发器。创建手动触发器在应用中只需点击查询面板中的 Add按钮然后选择Run Workflow。接着从下拉菜单中选择所需的工作流。如有需要可重命名该查询然后点击Run按钮即可触发工作流也可以将该查询添加到一个**事件处理器event handler**中从而在特定事件发生时自动触发工作流。从前端源码看Run Workflow 是查询面板中一个静态数据源static data source{ kind: workflows, id: null, name: Run Workflow, shortName: Workflows }并且仅当工作流功能开启isWorkflowsFeatureEnabled()时才会出现在候选列表中见 frontend/src/AppBuilder/QueryManager/constants.js。传递参数参数可以通过查询中的Params字段传递给工作流。参数key和其value值在Params字段中指定。例如想要通过手动触发器向工作流传递name和age参数可以按如下方式设置 Params 字段name: John Doe, age: 30与 Webhook 触发不同手动触发在 Params 字段中直接填写键值对key: value而无需声明数据类型——因为手动触发的参数类型校验在应用内由使用者自行保证。典型应用场景假设这样一个场景团队管理着多个 ToolJet 应用每个应用都需要对同一数据库执行查询以获取特定数据。与其在各个应用中重复编写这些步骤不如只创建一次工作流然后在任何需要的地方无缝集成。这正是手动触发的核心价值在查询面板中创建一个Run Workflow查询将该查询挂到按钮、表单提交等组件的事件处理器上通过Params字段传递当前应用上下文中的动态参数工作流内部完成数据库查询、数据处理等逻辑并将结果返回给调用方。这种一次编排、多处复用的模式将重复的业务逻辑收敛到工作流中统一维护降低多应用间的维护成本。触发方式对比与选型建议维度Webhook 触发手动触发发起方外部系统HTTP 请求ToolJet 应用内部鉴权强制 Bearer Token应用内用户身份无需额外 Token环境路由通过environment查询参数选择环境跟随应用当前环境参数方式声明类型webhookParams 传入值直接传键值对限流受WEBHOOK_THROTTLE_TTL/WEBHOOK_THROTTLE_LIMIT约束不受 webhook 限流影响典型场景外部系统集成、CI/CD 触发应用内按钮/事件触发、跨应用复用逻辑选型建议当工作流需要被应用外部的系统触发如第三方平台回调、定时任务平台、CI 流水线时使用 Webhook 触发当工作流仅需在 ToolJet 应用内部按需执行或需要作为可复用的业务逻辑单元嵌入多个应用时使用手动触发。小结触发器是 ToolJet 工作流体系的入口。Webhook 触发器通过唯一的端点 URL 和强制 Bearer Token 鉴权将工作流能力开放给外部系统并可通过startTrigger.params接收强类型参数手动触发器则通过查询面板的 Run Workflow 选项将工作流无缝嵌入应用的事件链路。结合 server/src/modules/workflows/module.ts 中的限流配置与 workflow-webhooks.spec.ts 中的完整测试用例可以确认Webhook 端点为版本化路由/api/v2/webhooks/workflows/:id/trigger参数校验严格类型不符返回 400环境路由清晰无效环境返回 404限流策略可配置默认 60 秒窗口 100 次请求。掌握这两类触发器的配置与原理即可根据业务场景灵活选择触发方式构建稳定可靠的工作流自动化体系。【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考