如何用 Twenty 工作流的 Webhook 触发器接收外部服务数据并自动创建记录【免费下载链接】twentyThe open alternative to Salesforce, designed for AI.项目地址: https://gitcode.com/GitHub_Trending/tw/twenty如果你的表单、第三方应用或其他系统产生了新的联系人/客户数据而你又希望在 Twenty 里不用手动录入就能生成对应记录那么 Webhook 触发器就是文档给出的集成路径外部服务向 Twenty 提供的一个唯一 URL 发送数据工作流被触发后由Create Record动作把数据写入指定对象。这篇指南对应 Twenty 官方文档中的 Set Up a Webhook Trigger适用于网页表单提交如联系表单生成 lead、第三方应用如 Stripe 支付后创建客户记录、自建集成以及 Zapier / Make / n8n 等无代码工具的对接场景。前置条件已有一个 Twenty 工作区并能访问Settings → Workflows外部服务支持向指定端点发送 HTTP 请求。Twenty 的 Webhook 触发器支持外部服务通过GET 或 POST请求启动工作流见 Workflow Triggers。一个限制需要预先知晓Webhook 触发器的鉴权配置在官方文档中仍标注为coming soon即文档未提供对入站请求做鉴权的配置项接入前请确认你所在环境的网络边界要求。第一步创建工作流并选择 Webhook 触发器进入Settings → Workflows点击 New Workflow给工作流命名例如 “Website Form Submission”点击触发器块选择Webhook。选择后Twenty 会为该工作流生成一个唯一的 Webhook URL文档中给出的示例格式为https://api.twenty.com/webhooks/workflow/abc123...以上为文档示例你的工作流会生成自己的 URL。在界面上复制这个 URL——它就是外部服务需要调用的端点。第二步定义预期的数据体POST 请求对于POST请求需要告诉 Twenty 你预期收到什么数据点击Define expected body输入一份与外部服务实际发送内容一致的 JSON 样例点击Save。文档给出的样例如下示例数据请按你的服务实际返回的字段调整{ firstName: John, lastName: Doe, email: johnexample.com, company: Acme Inc, message: Interested in your product }保存后这些字段会生成变量供工作流后续步骤引用。这一步的作用是让 Twenty 明确知道要接收哪些数据并在后面的动作里提供可选择的字段。第三步添加 Create Record 动作并映射字段接下来添加使用 Webhook 数据的动作。以文档中的示例——创建一条 People联系人记录为例添加Create Record动作选择目标对象People按下面方式映射字段值引用触发器数据字段值First Name{{trigger.body.firstName}}Last Name{{trigger.body.lastName}}Email{{trigger.body.email}}CompanySearch or create based on{{trigger.body.company}}{{trigger.body.xxx}}中的xxx必须对应第二步Define expected body里定义的字段名。关于 Create Record 动作本身的配置规则——选择目标对象、必填/可选字段、使用前序步骤数据或手工值填字段——见 Workflow Actions该动作的输出新建的记录数据也可供后续步骤使用。如果你不确定记录是否已存在文档还提供了Upsert Record动作它先按匹配条件搜索记录找到则更新、找不到则新建。匹配可用 People 的 email、Companies 的 domain、任意对象的 ID 或任何标记为 Unique 的字段且至少要填入一个唯一标识符。第四步激活前测试 Webhook官方要求在激活工作流之前先测试。文档给了两种测试方式。方式一cURL。下面命令中的 URL 是文档示例需替换为你在第一步复制的 Webhook URL请求体与第二步定义的字段保持一致curl -X POST https://api.twenty.com/webhooks/workflow/abc123... \ -H Content-Type: application/json \ -d {firstName:Test,lastName:User,email:testexample.com}方式二Postman 或同类工具创建一个指向你的 Webhook URL 的 POST 请求将 Content-Type 头设为application/json填入你的测试 JSON 体发送后到工作流执行记录中检查。第五步验证工作流是否按预期执行发送测试请求后验证方式在 Workflow Runs 中有明确说明入口一打开该工作流点击右侧Runs面板查看该工作流最近的运行及状态入口二在侧边栏进入Workflow Runs视图跨所有工作流查看并可按状态、工作流、日期过滤。运行状态包含Running执行中、Completed成功完成、Failed出错停止、Waiting暂停例如等待 Delay 或 Form 提交。点击某次运行可以看到状态、开始时间、耗时、Trigger data启动工作流的输入即你 POST 的数据、Step outputs各步骤返回的数据以及失败时的错误信息。当某次运行 Failed 时文档给出的排查路径是打开失败运行 → 定位导致失败的步骤 → 查看错误信息。文档列出的常见原因包括缺少必填字段、数据格式无效、外部 API 错误、权限问题。如果问题出在字段映射修正后等待下次触发即可重新验证。第六步激活工作流测试通过后点击Activate使工作流生效之后外部服务每次向该 URL 发送符合预期结构的数据工作流就会自动执行并创建记录。处理非平铺的数据结构可选分支如果你的外部服务发送的不是上面那种平铺 JSON文档还给出了两种处理方式嵌套数据如果数据嵌套在对象中例如{ contact: { name: John Doe, email: johnexample.com }, source: website }则后续步骤用点路径引用{{trigger.body.contact.email}}。数组数据处理方式取决于业务场景条目数量未知例如要为每个条目各建一条记录添加Code动作解析数组再用Iterator逐项处理循环引用{{code.items}}条目位置固定例如位置 0 永远是“姓名”添加Code动作把各位置提取为具名字段再在后续步骤中分别选择。完整的数组处理细节见 Handle Arrays in Code Actions。一个贴近真实外部服务的完整案例是 Bring Typeform Submissions into TwentyTypeform 把答案放在form_response.answers数组里文档演示了用 Code 动作按位置或字段类型提取firstName、email等值再交给 Create Record 写入 People 对象最后通过“在 Typeform 提交一次测试响应 → 检查工作流运行确认数据已捕获 → 激活工作流”完成验证。相关文档Workflow Triggers全部触发器类型及选型对照表外部集成对应 Webhook 或 On a ScheduleWorkflow ActionsCreate Record、Upsert Record、Iterator 等动作的完整配置说明Workflow Runs运行状态、运行详情与失败排查【免费下载链接】twentyThe open alternative to Salesforce, designed for AI.项目地址: https://gitcode.com/GitHub_Trending/tw/twenty创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考