Automatisch 集成 Typeform深入解析 New entry 触发器的工作原理与配置指南【免费下载链接】automatischThe open source Zapier alternative. Build workflow automation without spending time and money.项目地址: https://gitcode.com/GitHub_Trending/au/automatischAutomatisch 作为开源的 Zapier 替代方案通过内置的 Typeform 应用集成让开发者可以基于 Typeform 表单提交事件构建工作流自动化。本文以官方文档中定义的New entry新提交触发器为核心结合仓库源码完整讲解该触发器的触发机制、OAuth 连接建立、Webhook 注册/注销生命周期、HMAC 签名校验以及测试运行的底层实现帮助你理解如何在自己搭建的 Automatisch 实例中接入 Typeform 并实现真正的自动化。触发器概览Typeform 应用只有一个 Webhook 触发器在 triggers.md 中Typeform 应用当前只暴露了一个触发器名称描述New entryTriggers when a new form is submitted.当有新表单提交时触发这个触发器定义在 new-entry/index.js其type为webhook意味着它属于被动接收型触发器——由 Typeform 平台在表单提交时主动向 Automatisch 推送事件而不是由 Automatisch 定时轮询polling拉取数据。Typeform 应用的触发器统一在 triggers/index.js 中导出目前仅包含newEntry一个成员而应用本身的元信息应用名Typeform、keytypeform、API 地址https://api.typeform.com等定义在 index.js。从源码结构看该触发器还引用了动态数据源listForms见 list-forms/index.js用于在配置触发器时下拉列出当前账号拥有的表单——这属于触发器配置时的动态选项并非触发器本身的轮询行为。触发器定义详解参数、来源与校验newEntry触发器的完整定义如下节选自 new-entry/index.jsexport default defineTrigger({ name: New entry, key: newEntry, type: webhook, description: Triggers when a new form is submitted., arguments: [ { label: Form, key: formId, type: dropdown, required: true, description: Pick a form to receive submissions., variables: false, source: { type: query, name: getDynamicData, arguments: [ { name: key, value: listForms, }, ], }, }, ], ... });各字段含义如下name / key触发器的显示名称与唯一标识。key: newEntry会作为流程内部引用 ID也被用于 Webhook URL 的组成部分。type: webhook声明这是 Webhook 型触发器。arguments用户在 Automatisch 流程编辑器中需要填写的参数。这里只有一个必填的Form表单下拉框key为formIdrequired: true表示必须选择一个表单才能创建流程variables: false表示该字段不支持引用流程变量。source下拉框选项的数据来源指向getDynamicData中的listForms动态数据。下拉框选项如何获取listForms 动态数据list-forms/index.js 实现了表单列表的拉取逻辑通过$.http.get(/forms)调用 Typeform REST API再将返回结果response.data.items映射为{ value: form.id, name: form.title }格式的选项。也就是说配置触发器时下拉框展示的是表单标题name而真正传给后端的值是表单 IDformId。触发器类型合法性校验所有触发器定义都会经过 define-trigger.js 的统一校验逻辑上触发器必须满足有pollInterval、type webhook、属于调度型everyNMinutes / everyHour / everyDay / everyWeek / everyMonth或 MCP 工具之一否则会抛出Trigger must have a poll interval or be a webhook错误。newEntry正属于type webhook分支因此通过校验并以webhook类型进入触发器的调度与管理体系。工作流程从新提交到流程执行一个完整的 Typeform → Automatisch 触发链路包含以下环节用户在 Automatisch 中创建Typeform 连接OAuth 授权详见下文。用户在流程编辑器添加 New entry 触发器选择一个目标表单。流程保存/发布时Automatisch 调用registerHook在 Typeform 平台上注册 Webhook 订阅把 Automatisch 生成的$.webhookUrl交给 Typeform。访客提交表单后Typeform 向该 Webhook URL 发送form_response事件请求头带typeform-signature签名。Automatisch 的 Webhook 入口校验签名后调用触发器的run方法把原始请求体推入执行步骤pushTriggerItem随后触发后续动作。流程被删除或停用时调用unregisterHook注销订阅。registerHook注册 Webhook 订阅newEntry通过registerHook向 Typeform 注册订阅new-entry/index.jsasync registerHook($) { const subscriptionPayload { enabled: true, url: $.webhookUrl, secret: appConfig.webhookSecretKey, }; await $.http.put( /forms/${$.step.parameters.formId}/webhooks/${$.flow.id}, subscriptionPayload ); },关键点请求方法是PUT路径为/forms/{formId}/webhooks/{flowId}——即以流程 ID 作为 Webhook ID保证一个流程一个订阅多个流程订阅同一表单时互不冲突。请求体中url是 Automatisch 为该流程生成的 Webhook 回调地址$.webhookUrl。secret取自全局配置appConfig.webhookSecretKeywebhookSecretKey是 Automatisch 后端 app.js 中的全局密钥配置项Typeform 会用它做后续事件签名Automatisch 侧用同一密钥校验。unregisterHook注销 Webhook 订阅流程删除时调用unregisterHooknew-entry/index.js通过 DELETE 请求移除/forms/{formId}/webhooks/{flowId}对应的订阅避免残留无效回调。run处理真实的 Webhook 事件Typeform 推送事件到达后run方法将原始请求体包装成数据项并推入执行管线new-entry/index.jsasync run($) { const dataItem { raw: $.request.body, meta: { internalId: Crypto.randomUUID(), }, }; $.pushTriggerItem(dataItem); },这里$.request.body就是 Typeform 发送的form_response事件 JSON包含event_type、form_response.form_id、form_response.answers等字段后续流程步骤可以直接消费这些字段。internalId使用Crypto.randomUUID()生成唯一 ID用于执行记录去重与展示。testRun无真实提交时也能测试为了让用户在尚未有真实表单提交时就能测试流程newEntry实现了testRunnew-entry/index.js逻辑为通过$.http.get(/forms/{formId})获取表单定义含标题、字段结构。通过$.http.get(/forms/{formId}/responses)拉取最近提交的响应。取responses.items[0]最近一条响应若表单尚无任何响应则直接返回空。手工构造一个与 Typeform 真实事件结构一致的form_response事件对象含form_id、token、landed_at、submitted_at、definition.fields、answers再$.pushTriggerItem推入管线。这样测试数据与真实 Webhook 事件的字段结构保持一致后续动作在测试与生产两种场景下的行为一致。注意testRun的internalId使用的是form_response.tokenTypeform 为每次提交生成的唯一令牌保证测试项具备稳定的去重键。安全机制Webhook 签名校验Typeform 在推送 Webhook 时会携带typeform-signature请求头Automatisch 通过 verify-webhook.js 进行 HMAC-SHA256 签名验证const verifySignature function (receivedSignature, payload) { const hash crypto .createHmac(sha256, appConfig.webhookSecretKey) .update(payload) .digest(base64); return receivedSignature sha256${hash}; };实现要点使用 Node.js 内置crypto模块以appConfig.webhookSecretKey为密钥对$.request.rawBody原始请求体字节串计算 HMAC-SHA256输出 Base64。与请求头typeform-signature比对格式必须为sha256base64完全一致才判定有效。校验使用原始 bodyrawBody而非解析后的 JSON避免序列化差异导致签名不一致。这与registerHook中提交的secret是一对同一个webhookSecretKey既用于 Typeform 端签名也用于 Automatisch 端验签从而防止伪造的 Webhook 请求触发流程。前置条件创建 Typeform 连接要使用 New entry 触发器必须先建立 Typeform 连接。官方连接指南见 connection.md完整步骤如下访问 Typeform 管理后台在侧边栏点击Developer apps开发者应用。点击Register a new app注册新应用。填写App name应用名称、App website应用网站与Developer email开发者邮箱。将 Automatisch 提供的OAuth Redirect URL填入 Typeform 应用页面的Redirect URI(s)字段。点击Register app注册应用。将 Typeform 生成的Client ID与Client Secret填入 Automatisch 的连接配置。在 Automatisch 点击Submit提交。连接创建完成即可开始配置流程。Typeform 应用声明supportsConnections: true认证方式为 OAuth2见 index.js。OAuth 授权时申请的作用域定义在 auth-scope.jsforms:read, forms:write, webhooks:read, webhooks:write, responses:read, accounts:read, workspaces:read, offline这些 scope 覆盖了触发器所需的全部能力forms:read拉取表单列表/定义、forms:write用于响应写入类场景、webhooks:read/webhooks:write注册与注销 Webhook、responses:readtestRun 读取最近响应、offline获取刷新令牌以维持长期访问。相关刷新令牌、凭据校验与 Webhook 验签分别实现在 auth/refresh-token.js、auth/verify-credentials.js 与 auth/verify-webhook.jsaddAuthHeader见 common/add-auth-header.js则在每个 API 请求前自动注入 Bearer Token。典型使用场景与注意事项表单提交实时通知将 New entry 触发器与 Slack、Discord、邮件SMTP等动作组合即可实现每当有用户提交 Typeform 表单自动推送通知的经典自动化流程这正是 Automatisch 作为 Zapier 替代方案的典型用法。数据沉淀触发后接 Google Sheets 或 PostgreSQL 动作把每次提交的form_response.answers写入表格或数据库实现无代码数据采集。去重与幂等真实事件与测试事件的internalId分别来自随机 UUID 与 Typeform 的响应token同一提交不会重复触发同一执行记录。签名校验失败排查若 Webhook 请求被拒请确认 Automatisch 环境变量中的webhookSecretKey与注册订阅时提交的secret一致且注册后 Typeform 侧未手工修改 secret。适用前提本文所述均为当前仓库automatisch中 Typeform 集成的实际实现Typeform 平台的 API 与开发者后台细节以其官方文档为准如需接入请自行部署 Automatisch 后端并在 config/app.js 中配置对应的 OAuth 凭据与webhookSecretKey。小结通过官方文档定义的 New entry 触发器Automatisch 以 Webhook 订阅 HMAC 签名校验的方式接入了 Typeform 表单提交事件。开发者只需在流程编辑器中选定一个表单即可获得与真实事件结构一致含 testRun 模拟数据的触发能力再配合其他动作应用搭建完整的自动化流程。从 triggers.md 到 new-entry/index.js再到签名校验与连接配置整条链路在仓库中均有完整实现可循。【免费下载链接】automatischThe open source Zapier alternative. Build workflow automation without spending time and money.项目地址: https://gitcode.com/GitHub_Trending/au/automatisch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Automatisch 集成 Typeform：深入解析 “New entry“ 触发器的工作原理与配置指南
Automatisch 集成 Typeform深入解析 New entry 触发器的工作原理与配置指南【免费下载链接】automatischThe open source Zapier alternative. Build workflow automation without spending time and money.项目地址: https://gitcode.com/GitHub_Trending/au/automatischAutomatisch 作为开源的 Zapier 替代方案通过内置的 Typeform 应用集成让开发者可以基于 Typeform 表单提交事件构建工作流自动化。本文以官方文档中定义的New entry新提交触发器为核心结合仓库源码完整讲解该触发器的触发机制、OAuth 连接建立、Webhook 注册/注销生命周期、HMAC 签名校验以及测试运行的底层实现帮助你理解如何在自己搭建的 Automatisch 实例中接入 Typeform 并实现真正的自动化。触发器概览Typeform 应用只有一个 Webhook 触发器在 triggers.md 中Typeform 应用当前只暴露了一个触发器名称描述New entryTriggers when a new form is submitted.当有新表单提交时触发这个触发器定义在 new-entry/index.js其type为webhook意味着它属于被动接收型触发器——由 Typeform 平台在表单提交时主动向 Automatisch 推送事件而不是由 Automatisch 定时轮询polling拉取数据。Typeform 应用的触发器统一在 triggers/index.js 中导出目前仅包含newEntry一个成员而应用本身的元信息应用名Typeform、keytypeform、API 地址https://api.typeform.com等定义在 index.js。从源码结构看该触发器还引用了动态数据源listForms见 list-forms/index.js用于在配置触发器时下拉列出当前账号拥有的表单——这属于触发器配置时的动态选项并非触发器本身的轮询行为。触发器定义详解参数、来源与校验newEntry触发器的完整定义如下节选自 new-entry/index.jsexport default defineTrigger({ name: New entry, key: newEntry, type: webhook, description: Triggers when a new form is submitted., arguments: [ { label: Form, key: formId, type: dropdown, required: true, description: Pick a form to receive submissions., variables: false, source: { type: query, name: getDynamicData, arguments: [ { name: key, value: listForms, }, ], }, }, ], ... });各字段含义如下name / key触发器的显示名称与唯一标识。key: newEntry会作为流程内部引用 ID也被用于 Webhook URL 的组成部分。type: webhook声明这是 Webhook 型触发器。arguments用户在 Automatisch 流程编辑器中需要填写的参数。这里只有一个必填的Form表单下拉框key为formIdrequired: true表示必须选择一个表单才能创建流程variables: false表示该字段不支持引用流程变量。source下拉框选项的数据来源指向getDynamicData中的listForms动态数据。下拉框选项如何获取listForms 动态数据list-forms/index.js 实现了表单列表的拉取逻辑通过$.http.get(/forms)调用 Typeform REST API再将返回结果response.data.items映射为{ value: form.id, name: form.title }格式的选项。也就是说配置触发器时下拉框展示的是表单标题name而真正传给后端的值是表单 IDformId。触发器类型合法性校验所有触发器定义都会经过 define-trigger.js 的统一校验逻辑上触发器必须满足有pollInterval、type webhook、属于调度型everyNMinutes / everyHour / everyDay / everyWeek / everyMonth或 MCP 工具之一否则会抛出Trigger must have a poll interval or be a webhook错误。newEntry正属于type webhook分支因此通过校验并以webhook类型进入触发器的调度与管理体系。工作流程从新提交到流程执行一个完整的 Typeform → Automatisch 触发链路包含以下环节用户在 Automatisch 中创建Typeform 连接OAuth 授权详见下文。用户在流程编辑器添加 New entry 触发器选择一个目标表单。流程保存/发布时Automatisch 调用registerHook在 Typeform 平台上注册 Webhook 订阅把 Automatisch 生成的$.webhookUrl交给 Typeform。访客提交表单后Typeform 向该 Webhook URL 发送form_response事件请求头带typeform-signature签名。Automatisch 的 Webhook 入口校验签名后调用触发器的run方法把原始请求体推入执行步骤pushTriggerItem随后触发后续动作。流程被删除或停用时调用unregisterHook注销订阅。registerHook注册 Webhook 订阅newEntry通过registerHook向 Typeform 注册订阅new-entry/index.jsasync registerHook($) { const subscriptionPayload { enabled: true, url: $.webhookUrl, secret: appConfig.webhookSecretKey, }; await $.http.put( /forms/${$.step.parameters.formId}/webhooks/${$.flow.id}, subscriptionPayload ); },关键点请求方法是PUT路径为/forms/{formId}/webhooks/{flowId}——即以流程 ID 作为 Webhook ID保证一个流程一个订阅多个流程订阅同一表单时互不冲突。请求体中url是 Automatisch 为该流程生成的 Webhook 回调地址$.webhookUrl。secret取自全局配置appConfig.webhookSecretKeywebhookSecretKey是 Automatisch 后端 app.js 中的全局密钥配置项Typeform 会用它做后续事件签名Automatisch 侧用同一密钥校验。unregisterHook注销 Webhook 订阅流程删除时调用unregisterHooknew-entry/index.js通过 DELETE 请求移除/forms/{formId}/webhooks/{flowId}对应的订阅避免残留无效回调。run处理真实的 Webhook 事件Typeform 推送事件到达后run方法将原始请求体包装成数据项并推入执行管线new-entry/index.jsasync run($) { const dataItem { raw: $.request.body, meta: { internalId: Crypto.randomUUID(), }, }; $.pushTriggerItem(dataItem); },这里$.request.body就是 Typeform 发送的form_response事件 JSON包含event_type、form_response.form_id、form_response.answers等字段后续流程步骤可以直接消费这些字段。internalId使用Crypto.randomUUID()生成唯一 ID用于执行记录去重与展示。testRun无真实提交时也能测试为了让用户在尚未有真实表单提交时就能测试流程newEntry实现了testRunnew-entry/index.js逻辑为通过$.http.get(/forms/{formId})获取表单定义含标题、字段结构。通过$.http.get(/forms/{formId}/responses)拉取最近提交的响应。取responses.items[0]最近一条响应若表单尚无任何响应则直接返回空。手工构造一个与 Typeform 真实事件结构一致的form_response事件对象含form_id、token、landed_at、submitted_at、definition.fields、answers再$.pushTriggerItem推入管线。这样测试数据与真实 Webhook 事件的字段结构保持一致后续动作在测试与生产两种场景下的行为一致。注意testRun的internalId使用的是form_response.tokenTypeform 为每次提交生成的唯一令牌保证测试项具备稳定的去重键。安全机制Webhook 签名校验Typeform 在推送 Webhook 时会携带typeform-signature请求头Automatisch 通过 verify-webhook.js 进行 HMAC-SHA256 签名验证const verifySignature function (receivedSignature, payload) { const hash crypto .createHmac(sha256, appConfig.webhookSecretKey) .update(payload) .digest(base64); return receivedSignature sha256${hash}; };实现要点使用 Node.js 内置crypto模块以appConfig.webhookSecretKey为密钥对$.request.rawBody原始请求体字节串计算 HMAC-SHA256输出 Base64。与请求头typeform-signature比对格式必须为sha256base64完全一致才判定有效。校验使用原始 bodyrawBody而非解析后的 JSON避免序列化差异导致签名不一致。这与registerHook中提交的secret是一对同一个webhookSecretKey既用于 Typeform 端签名也用于 Automatisch 端验签从而防止伪造的 Webhook 请求触发流程。前置条件创建 Typeform 连接要使用 New entry 触发器必须先建立 Typeform 连接。官方连接指南见 connection.md完整步骤如下访问 Typeform 管理后台在侧边栏点击Developer apps开发者应用。点击Register a new app注册新应用。填写App name应用名称、App website应用网站与Developer email开发者邮箱。将 Automatisch 提供的OAuth Redirect URL填入 Typeform 应用页面的Redirect URI(s)字段。点击Register app注册应用。将 Typeform 生成的Client ID与Client Secret填入 Automatisch 的连接配置。在 Automatisch 点击Submit提交。连接创建完成即可开始配置流程。Typeform 应用声明supportsConnections: true认证方式为 OAuth2见 index.js。OAuth 授权时申请的作用域定义在 auth-scope.jsforms:read, forms:write, webhooks:read, webhooks:write, responses:read, accounts:read, workspaces:read, offline这些 scope 覆盖了触发器所需的全部能力forms:read拉取表单列表/定义、forms:write用于响应写入类场景、webhooks:read/webhooks:write注册与注销 Webhook、responses:readtestRun 读取最近响应、offline获取刷新令牌以维持长期访问。相关刷新令牌、凭据校验与 Webhook 验签分别实现在 auth/refresh-token.js、auth/verify-credentials.js 与 auth/verify-webhook.jsaddAuthHeader见 common/add-auth-header.js则在每个 API 请求前自动注入 Bearer Token。典型使用场景与注意事项表单提交实时通知将 New entry 触发器与 Slack、Discord、邮件SMTP等动作组合即可实现每当有用户提交 Typeform 表单自动推送通知的经典自动化流程这正是 Automatisch 作为 Zapier 替代方案的典型用法。数据沉淀触发后接 Google Sheets 或 PostgreSQL 动作把每次提交的form_response.answers写入表格或数据库实现无代码数据采集。去重与幂等真实事件与测试事件的internalId分别来自随机 UUID 与 Typeform 的响应token同一提交不会重复触发同一执行记录。签名校验失败排查若 Webhook 请求被拒请确认 Automatisch 环境变量中的webhookSecretKey与注册订阅时提交的secret一致且注册后 Typeform 侧未手工修改 secret。适用前提本文所述均为当前仓库automatisch中 Typeform 集成的实际实现Typeform 平台的 API 与开发者后台细节以其官方文档为准如需接入请自行部署 Automatisch 后端并在 config/app.js 中配置对应的 OAuth 凭据与webhookSecretKey。小结通过官方文档定义的 New entry 触发器Automatisch 以 Webhook 订阅 HMAC 签名校验的方式接入了 Typeform 表单提交事件。开发者只需在流程编辑器中选定一个表单即可获得与真实事件结构一致含 testRun 模拟数据的触发能力再配合其他动作应用搭建完整的自动化流程。从 triggers.md 到 new-entry/index.js再到签名校验与连接配置整条链路在仓库中均有完整实现可循。【免费下载链接】automatischThe open source Zapier alternative. Build workflow automation without spending time and money.项目地址: https://gitcode.com/GitHub_Trending/au/automatisch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考