Automatisch 中 SurveyMonkey「New Response Notification」触发器全解析：基于 Webhook 的问卷完成事件接入指南

Automatisch 中 SurveyMonkey「New Response Notification」触发器全解析基于 Webhook 的问卷完成事件接入指南【免费下载链接】automatischThe open source Zapier alternative. Build workflow automation without spending time and money.项目地址: https://gitcode.com/GitHub_Trending/au/automatisch本文以 Automatisch 开源仓库中 SurveyMonkey 应用的触发器文档triggers.md为骨架结合其后端实现源码完整讲解 SurveyMonkey 触发器「New Response notification」的声明方式、参数配置、Webhook 注册与退订机制、触发与测试流程以及使用该触发器所需的连接OAuth前置条件。读完本文你将能够在 Automatisch 中基于“问卷完成”事件搭建自动化工作流并理解其底层的response_completedWebhook 回调原理。一、SurveyMonkey 触发器总览文档中的核心定义Automatisch 文档体系中每个 App 页面如 triggers.md、actions.md通过 frontmatter 中的items列表描述该应用对外暴露的能力清单。SurveyMonkey 触发器文档明确列出了唯一一个触发器触发器名称说明New response notificationTriggers a notification upon the completion of your survey.当你的问卷被填写完成后触发一次通知这一声明与后端源码一一对应在 triggers/index.js 中SurveyMonkey 应用的触发器集合只导出一个newResponseNotification触发器随后该集合被挂载到应用定义中见 index.js。从使用场景看这个触发器适合“表单提交后自动通知”类工作流例如问卷完成后向团队成员推送消息、把答卷写入数据库、或触发后续的客户跟进流程。由于它属于Webhook 类型触发器事件由 SurveyMonkey 服务器实时推送到 Automatisch无需轮询因此通知具备低延迟特性。二、触发器定义文件声明结构逐字段解读触发器的完整实现在 new-response-notification/index.js其核心结构如下export default defineTrigger({ name: New response notification, key: newResponseNotification, type: webhook, description: Triggers a notification upon the completion of your survey., arguments: [ { label: Survey, key: surveyId, type: dropdown, required: true, description: , variables: true, source: { type: query, name: getDynamicData, arguments: [ { name: key, value: listSurveys }, ], }, }, ], // run / testRun / registerHook / unregisterHook 见下文 });各字段含义name/key触发器对外显示名称与内部唯一标识符与文档中items列表的name保持一致。type: webhook声明这是一个 Webhook 型触发器。在 define-trigger.js 中可以看到 Automatisch 对触发器的类型约束凡是type webhook或定义了pollInterval的触发器均被视为合法否则会抛出Trigger must have a poll interval or be a webhook异常。SurveyMonkey 触发器正是借由 Webhook 类型获得合法性校验。arguments配置表单字段。这里只有一个必填下拉框surveyId用于指定要监听的问卷。值得注意的一点arguments中配置了variables: true意味着surveyId还可以引用工作流中的变量例如来自上游步骤的动态值而不仅是手动选择固定问卷。三、调查问卷参数基于动态数据的下拉选择surveyId字段的类型是dropdown其数据来源指向getDynamicData动态数据接口中的listSurveys。该接口实现在 dynamic-data/list-surveys/index.jsconst params { page: 1, per_page: 100, sort_by: date_modified, sort_order: DESC, }; let fetchedSum 0; let total; do { const { data } await $.http.get(/v3/surveys, { params }); params.page params.page 1; fetchedSum fetchedSum data.data.length; total data.total; if (data.data) { for (const survey of data.data) { surveys.data.push({ value: survey.id, name: survey.title }); } } } while (fetchedSum total);其工作方式是调用 SurveyMonkey APIGET /v3/surveys按每页 100 条、按最近修改时间倒序拉取当前账号下的全部问卷并通过fetchedSum total的循环条件做全量分页最终返回{ value: survey.id, name: survey.title }形式的下拉选项。因此你在 Automatisch 的触发器配置界面选择「Survey」时看到的是账号下所有问卷的标题选中的值则是问卷 ID。四、Webhook 生命周期注册与退订的实现原理作为 Webhook 触发器Automatisch 会在工作流启用时自动调用registerHook向 SurveyMonkey 注册回调并在工作流停用时调用unregisterHook清理回调。4.1 registerHook订阅 response_completed 事件async registerHook($) { const surveyId $.step.parameters.surveyId; const body JSON.stringify({ name: $.flow.id, subscription_url: $.webhookUrl, event_type: response_completed, object_type: survey, object_ids: [surveyId], }); const { data } await $.http.post(/v3/webhooks?bypass_pingtrue, body, { headers: { Content-Type: application/json }, }); await $.flow.setRemoteWebhookId(data.id); }这里的关键细节订阅对象object_type: survey、object_ids: [surveyId]即只监听配置表单中选中的那一个问卷。事件类型event_type: response_completed对应 SurveyMonkey 的“答卷完成”事件与文档中 “Triggers a notification upon the completion of your survey” 的描述完全一致。回调地址subscription_url: $.webhookUrl这是 Automatisch 为当前工作流动态生成的接收地址SurveyMonkey 会向该地址推送事件。回调命名name: $.flow.id把 webhook 名称与工作流 ID 绑定便于后续管理。bypass_pingtrue注册时跳过 SurveyMonkey 的 ping 测试请求简化注册流程。结果保存注册成功后通过$.flow.setRemoteWebhookId(data.id)把 SurveyMonkey 返回的 webhook ID 关联到当前工作流供退订时使用。4.2 unregisterHook删除远程 Webhookasync unregisterHook($) { await $.http.delete(/v3/webhooks/${$.flow.remoteWebhookId}); }工作流被停用或删除时Automatisch 会携带此前保存的remoteWebhookId调用 SurveyMonkey 的DELETE /v3/webhooks/{id}接口确保远程订阅被及时清理避免产生无效的 Webhook 调用与资源占用。五、事件触发与测试运行run / testRun5.1 run接收并推送触发数据async run($) { const dataItem { raw: $.request.body, meta: { internalId: Crypto.randomUUID() }, }; $.pushTriggerItem(dataItem); }当 SurveyMonkey 向$.webhookUrl推送response_completed事件时Automatisch 调用run。实现将回调请求的原始 body即 SurveyMonkey 事件载荷作为raw数据推入工作流并利用 Node.js 内置的crypto.randomUUID()为每条记录生成唯一的internalId用于执行记录的幂等去重。下游步骤可以直接引用该原始载荷中的字段如答卷 ID、完成时间、受访者信息等。5.2 testRun无真实事件时的测试数据async testRun($) { const lastExecutionStep await $.getLastExecutionStep(); if (!isEmpty(lastExecutionStep?.dataOut)) { $.pushTriggerItem({ raw: lastExecutionStep.dataOut, meta: { internalId: }, }); } }在编辑器中进行“测试并继续”时如果当前流程还没有真实事件到来testRun会从最近的执行步骤中取出上一次的dataOut作为测试数据推送方便你在没有真实答卷的情况下预览下游步骤的输出。六、连接前置条件OAuth 认证与所需 Scopes要使用该触发器必须先建立可用的 SurveyMonkey 连接。完整的连接步骤见 connection.md核心流程如下在 SurveyMonkey 开发者后台My Apps 页面创建一个 App。在Settings页面把 Automatisch 提供的OAuth Redirect URL填入 SurveyMonkey 的OAuth Redirect URIs字段并保存。在Scopes部分勾选以下权限并更新Create/Modify Surveys、View Surveys、View Collectors、View Responses、Create/Modify Contacts、View Contacts、Create/Modify Webhooks、View Users、View Webhooks。将 SurveyMonkey 的Client ID与Secret分别填入 Automatisch 连接的对应字段并提交。从源码可以进一步印证连接机制认证字段定义在 auth/index.js包含只读的oAuthRedirectUrl值形如{WEB_APP_URL}/app/surveymonkey/connections/add支持一键复制、clientId与clientSecret三个字段。令牌换取在 verify-credentials.js使用授权码向https://api.surveymonkey.com/oauth/token发起grant_typeauthorization_code请求换取access_token、token_type、access_url与expires_in并保存到连接数据中。请求拦截器应用注册了beforeRequest: [setBaseUrl, addAuthHeader]见 index.js。其中 set-base-url.js 会把后续请求的 baseURL 指向 OAuth 返回的access_url即当前用户专属的 API 域名而 add-auth-header.js 会自动为每个请求附加Authorization: {tokenType} {accessToken}头。这也解释了为何触发器与动态数据请求都只需写相对路径/v3/...。需要特别说明registerHook调用POST /v3/webhooks属于Create/Modify Webhooks权限范围listSurveys调用GET /v3/surveys属于View Surveys权限范围。因此 connection 文档中要求勾选的 Scopes 与触发器实际运行的权限需求是严格对齐的缺一不可。七、实战落地把 New Response Notification 用起来在 Automatisch 中搭建一个基于该触发器的完整工作流操作路径如下创建连接进入 SurveyMonkey 连接页按上文第六节完成 OAuth 授权。新建流程在流程编辑器中添加触发器步骤选择SurveyMonkey应用下的New response notification。选择问卷在触发器配置面板的Survey下拉框中从动态加载的问卷列表里选择目标问卷对应surveyId参数必填。测试触发点击测试按钮Automatisch 会先调用testRun用历史数据预览同时registerHook会立即在 SurveyMonkey 侧注册response_completed订阅。此后任意受访者完成该问卷事件都会实时推送到流程。串联动作在触发器后添加任意动作步骤例如通知类应用或数据处理步骤引用触发器输出的raw载荷字段完成业务逻辑。一个典型的真实链路示例问卷完成New response notification→ 向团队 Slack 频道推送“有新的答卷”通知 → 把答卷摘要写入数据库。整个过程由 SurveyMonkey 的 Webhook 实时驱动无需任何轮询或手工触发。八、小结SurveyMonkey 在 Automatisch 中只暴露一个 Webhook 型触发器New response notification对应 SurveyMonkey 的response_completed事件。触发器通过surveyId下拉参数数据来自listSurveys动态数据接口精确锁定目标问卷。Webhook 的注册与退订由registerHook/unregisterHook全自动管理run推送原始载荷testRun复用历史执行数据便于调试。使用前需完成包含 Webhooks、Surveys、Responses 等 Scopes 的 OAuth 连接且请求会自动携带认证头与用户专属 baseURL。若想进一步深入可继续阅读同一文档体系下的 actions.mdCreate contact 动作与 connection.md完整连接指南并结合 new-response-notification/index.js 源码逐行对照学习。【免费下载链接】automatischThe open source Zapier alternative. Build workflow automation without spending time and money.项目地址: https://gitcode.com/GitHub_Trending/au/automatisch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考