Activepieces Outseta 集成详解Webhook 事件触发、Admin API 鉴权与 CRM/Billing 自动化实战【免费下载链接】activepiecesAI Agents MCPs AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows AI Agents • MCPs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/ac/activepiecesActivepieces 的 Outseta 社区 Pieceactivepieces/piece-outseta为 Outseta CRM 与 Billing 提供了一组基于 Webhook 的事件触发器和管理员 API 动作让自动化流程能够响应Outseta 中账户、联系人、订阅、发票等实体的变化并在流程内以最小化的 API 调用完成查询、创建与状态变更。本文以仓库中 Outseta Piece 的 README 为主线结合 入口注册文件、鉴权定义 与 底层 HTTP 客户端 的源码实现完整讲解该集成的连接配置、触发器工作原理、动作体系以及若干源码级实现细节帮助你把它真正用起来并理解其底层机制。一、集成定位事件驱动 最小化 API 调用README 对该 Piece 的定位非常明确提供 Outseta CRM 和 Billing 的Webhook 触发器与查询动作面向事件驱动型工作流响应 Outseta 事件accounts、people、subscriptions、payments并用最小化的只读 API 调用为流程补充数据。在 入口文件 中该 Piece 通过createPiece注册关键元数据如下export const outseta createPiece({ displayName: Outseta, description: Triggers and actions for Outseta CRM and Billing, auth: outsetaAuth, minimumSupportedRelease: 0.20.0, categories: [PieceCategory.SALES_AND_CRM], // triggers 与 actions 注册见下文 });值得注意的是 package.json 中当前包版本为0.2.3而 README 标注的v0.1.0 – initial release是初始发布版本——也就是说该 Piece 已经历了多轮迭代当前源码中的动作与触发器数量远超 README 首版描述的范围后文会完整列出。该 Piece 依赖activepieces/pieces-framework、activepieces/pieces-common等 workspace 内包构建属于 Activepieces 社区 Piece 体系的一部分。二、连接配置基于 Outseta Admin API 的自定义鉴权README 明确说明该 Piece 使用 OutsetaAdmin API所需凭证为三项Outseta 域名如https://yourcompany.outseta.com、API Key、API Secret。auth.ts 使用PieceAuth.CustomAuth实现了这一鉴权displayName 为Outseta Admin API其description直接给出了在 Outseta 后台获取凭证的操作路径登录 Outseta 账户进入Settings → Integrations → API复制API Key与API Secret域名即你的 Outseta 子域例如https://yourcompany.outseta.com。三个属性均为必填的Property.ShortText属性显示名说明domainOutseta Domain完整的 Outseta 域名 URL例如https://yourcompany.outseta.comapiKeyAPI Key在 Outseta → Settings → Integrations → API 中获取apiSecretAPI Secret与 API Key 同处获取validate回调在保存连接时发起一次真实请求来验证凭证有效性validate: async ({ auth }) { const client new OutsetaClient({ domain: auth.domain, apiKey: auth.apiKey, apiSecret: auth.apiSecret, }); await client.getany(/api/v1/crm/people?limit1); // 成功即视为凭证有效 return { valid: true }; }从源码结构看校验逻辑选择了一次开销极小的GET /crm/people?limit1调用任何 2xx 响应都说明 Key/Secret 组合可用否则返回Invalid Api Key or secret key错误提示。三、Webhook 触发器手动配置的事件源README 中Triggers一节的两个关键约束在源码中得到了印证Triggers are implemented as manual webhooks. Webhook URLs must be configured in the Outseta dashboard.也就是说触发器是Webhook 策略TriggerStrategy.WEBHOOK的手动模式Activepieces 侧不会自动向 Outseta 注册回调需要人工把 Webhook URL 粘贴到 Outseta 后台。new-account-event.ts 中的props.setup就是给操作者的配置指引进入 Outseta 的Settings → Notifications → Add Notification选择对应事件把 Activepieces 提供的 Webhook URL{{webhookUrl}}占位符渲染后的地址粘贴到 callback 字段每个事件创建一条通知全部指向同一个 Webhook URL。这与onEnable/onDisable的空实现是相互对应的——由于注册和移除都必须人工完成这两个生命周期钩子只能留注释说明async onEnable() { // Webhook must be configured manually in Outseta (Settings → Notifications) }, async onDisable() { // Webhook must be removed manually in Outseta },当前注册的 6 个事件触发器README 首版列出了 Account created / Account updated / Person created / Person updated / Subscription created / Subscription updated / Invoice paid / Payment succeeded 共 8 类事件。当前 index.ts 实际注册的是 6 个按实体域划分的触发器通过eventSubTypes多选下拉框细分事件触发器name覆盖范围New Account Eventnew_account_event账户域全部事件生命周期、阶段变更、计费、订阅、发票共 20 个事件选项 Custom/Note/Email/Phone Call/Meeting/Chat 等手动活动事件New Person Eventnew_person_event联系人域事件New Deal Eventnew_deal_event商机域事件New Task Eventnew_task_event任务域事件New Plan Eventnew_plan_event计费计划目录事件Plan Created / Plan UpdatedNew Add-On Eventnew_add_on_event附加项目录事件以 new-account-event.ts 为例其eventSubTypes选项逐字镜像了 Outseta 管理后台的下拉菜单Settings → Notifications → Add Notification → Activity Type包括account_created、account_updated、account_stage_updated、account_billing_invoice_created、account_paid_subscription_created、account_subscription_payment_collected、account_subscription_payment_declined等这样用户在 Outseta 侧配置通知时可以与 Activepieces 侧的选项 1:1 对应。触发器的运行逻辑非常直接run方法把 Outseta 推送的请求体原样作为步骤输出每个 Webhook 投递一个实体对象具体事件的细节嵌套在其ActivityEventData字段中async run(context) { return [context.payload.body as Recordstring, unknown]; }sampleData则给出了典型 payload 形状例如 Account 触发器示例包含Uid、Name、AccountStage、AccountStageLabel、PersonAccount、Subscriptions、ActivityEventData、Created、Updated等字段可直接用于流程中$text引用的调试参考。另一个细节是test方法它不回放历史 Webhook而是用同一套鉴权主动调用 Admin API按用户勾选的事件类型拉取最近 5 条相关记录全为*_created类型时按Created倒序否则按Updated倒序方便在启用前确认连接和数据形态const onlyCreate selected.length 0 selected.every((s) s.endsWith(_created)); const orderProperty onlyCreate ? Created : Updated; const res await client.get(/api/v1/crm/accounts?limit5orderBy${orderProperty}%20DESC);四、动作体系从 3 个只读查询扩展到全量 CRUD 与 Billing 操作README 首版只列出三个只读查询动作Get account、Get person、Get subscription。而当前 index.ts 注册的动作已按领域分组扩展为 45 个具名动作加 1 个通用自定义 API 调用完整清单如下Retrieve读取Get Account、Get Person、Get Deal、Get Subscription、Get Last PaymentCreate / Find or Add创建或查找Create Account、Create Deal、Find or Add Person、Find or Add DealUpdate / Delete更新与删除Update Account、Update Person、Update Deal、Delete Account、Delete Person、Delete DealList列表自动翻页List Accounts、List Persons、List Deals、List Plans、List Add-Ons、List Discounts、List Cases、List TransactionsBilling — Subscription订阅管理Change Account Plan、Cancel Subscription、Remove Cancellation、Add Discount to Subscription、Add Add-On Usage、Add Add-On to Subscription、Extend Trial Subscription、Update Payment InformationBilling — Catalog / Invoice目录与发票Create Discount、Add Invoice、Add Invoice Payment、Send Invoice Email、Process PaymentCRM — Membership / Activity成员与活动Manage Account Membership、Update Account Membership、Add Custom ActivityEmail / Support邮件与支持Manage Email List Subscription、Send Confirmation Email、Add Case、Add ReplyCustom API Call通过createCustomApiCallAction暴露的逃生舱允许在流程中直接对${auth.domain}/api/v1发起任意请求鉴权头自动映射为Outseta ${apiKey}:${apiSecret}见 index.ts 中的 authMapping。下面挑三个有代表性的动作说明其实现思路。Find or Add Person以邮箱为去重键的幂等联系人同步find-or-add-person.ts 实现了查得到就返回、查不到就创建的经典 upsert 语义用getAllPages对/api/v1/crm/people?Email...做全量翻页查询客户端再做一次大小写不敏感的精确邮箱匹配item.Email?.toLowerCase() email.toLowerCase()命中则返回{ created: false, person }未命中则组装FirstName、LastName、PhoneMobile、PhoneWork及嵌套的MailingAddress对象后POST /api/v1/crm/people返回{ created: true, person }。aiMetadata中还显式标注了idempotent: false因为它可能产生创建副作用并说明Email 是去重键复用同一邮箱是安全的传入不同邮箱会创建新联系人——这类元数据供 AI Agent 组装流程时判断动作安全性。Get Account按 UID 或主联系人邮箱双路解析get-account.ts 展示了 Outseta 数据模型的一个典型处理当按主联系人邮箱查找时先按邮箱翻页查出 person再从其PersonAccount成员关系里取第一个关联账户的Uid取到 UID 后再拉取账户详情。详情请求使用带fields的展开查询const account await client.getany( /api/v1/crm/accounts/${accountUid}?fields*,BillingAddress.*,MailingAddress.* ,PrimaryContact.*,CurrentSubscription.*,CurrentSubscription.Plan.* ,CurrentSubscription.Plan.PlanFamily.*,CurrentSubscription.SubscriptionAddOns.* ,CurrentSubscription.SubscriptionAddOns.AddOn.* );源码注释特别强调了一个 API 陷阱fields参数中的前导*是必须的——一旦提供fieldsOutseta 只返回列出的字段缺少*时Name、AccountStage、BillingAddress等顶层标量字段会全部为 null。动作最终把嵌套结构拍平为 snake_case 的扁平输出uid、plan_name、billing_address_city、add_ons等并统一了周期性计划用renewal_date、一次性计划用end_date的validity_date字段方便下游步骤引用。Cancel SubscriptionAPI 缺口上的立即取消组合技cancel-subscription.ts 体现了针对 Outseta API 现实限制的设计取舍Outseta 没有专门的立即取消端点PUT /crm/accounts/cancellation/{uid}只能把取消安排在账单期末。因此当勾选cancelImmediately时动作会先 GET 完整账户展开BillingAddress、PersonAccount、Subscriptions等嵌套集合把AccountStage置为6Expired再整体 PUT 回去强制立即到期。这段代码还记录了两个极具实战价值的 API 细节CancelationReason是 Outseta API 的真实字段名单个 l的拼写照抄 API 而非纠正拼写PUT 整体账户前必须把{items: [...]}形态的封装数组展开成纯数组否则服务端可能把信封结构解释为空集合静默清空计费、成员和订阅数据。五、底层实现OutsetaClient 与分页翻页的正确姿势所有动作与触发器共用 common/client.ts 中的OutsetaClient。它封装了三件事constructor(auth: OutsetaAuth) { this.baseUrl auth.domain.replace(/\/$/, ); // 去除尾部斜杠 this.authHeader Outseta ${auth.apiKey}:${apiSecret}; // 自定义鉴权头 }请求头每次请求携带Authorization: Outseta apiKey:apiSecret与Content-Type: application/json错误处理非 2xx 响应统一抛出Outseta API error (status): body错误让 Activepieces 的步骤失败信息直接携带上游 API 的原始响应体兼容大小写Outseta 不同接口的列表字段可能是items或Items客户端统一以res?.items ?? res?.Items ?? []兜底。分页陷阱Outseta 的 offset 是页不是条getAllPages是 List 系列动作的基石其注释记录了针对线上 API 的实测结论/crm/people共 182 条时limit100 offset0返回第 0–99 条limit100 offset1返回第 100–181 条offset2返回空——即offset参数按页计而不是按条数计。因此实现中每轮循环page 1而不是page pageSizelet page 0; while (true) { const res await this.getPaginatedResponseT( ${basePath}${separator}limit${pageSize}offset${page} ); const items: T[] res?.items ?? res?.Items ?? []; allItems.push(...items); if (items.length pageSize) break; page 1; }如果你直接调用 Outseta API 做全量导出这条offset 按页递增的规则同样适用按条数递增会漏拉数据。动态自定义属性表单与动态下拉框Outseta 允许在工作区为 Account / Person / Deal 定义自定义属性。custom-properties.ts 的customPropertiesProp在表单渲染时调用/api/v1/attributes/{entity}/definitions?limit100拉取属性定义并按ControlType自动推断控件类型Text → 短文本、Date → 日期、Select → 单选下拉、CheckboxList → 多选下拉跳过Hidden属性。配套的mergeCustomProperties负责把用户填写值合并进请求体并处理了一个格式细节CheckboxList 的值在 Outseta 中存储为 JSON 字符串化的数组因此提交前需要JSON.stringify。dropdowns.ts 则提供了一批带鉴权的Property.Dropdown工厂Pipeline、Pipeline Stage通过refreshers: [pipelineUid]实现级联刷新、Plan可按账户当前订阅的PlanFamily过滤、Add-On、Email List、Discount只显示IsActive ! false的优惠券标签附带折扣幅度。这些下拉框在凭证缺失或 API 失败时都返回disabled: true加占位提示如Connect your Outseta account first.而不是抛错中断表单渲染。六、Webhook 安全边界与适用限制README 用专门一节声明了安全模型这一点值得在部署前明确Webhook signature verification is NOT implemented in v1.Security relies on the secrecy of the webhook URL.即当前版本不校验 Outseta 推送的签名安全性完全依赖 Webhook URL 本身的保密性。从 各触发器源码 可以看到run直接信任context.payload.body没有任何签名比对逻辑。生产环境落地时应注意Activepieces 生成的 Webhook 端点路径本身是随机生成的长 URL泄露风险主要来自日志、转发链路和截图若你的网络架构允许可以在反向代理层限制该 Webhook 路径的来源对于Invoice paid / Payment succeeded这类高敏感事件触发后的动作建议先做只读校验如 Get Last Payment再执行资金相关操作。此外还有两条适用前提触发器需要手动在 Outseta 后台Settings → Notifications为每个事件创建通知停用流程后需手动移除避免回调打到已删除的流程Piece 元数据声明minimumSupportedRelease: 0.20.0即运行环境需为不低于该版本的 Activepieces。七、小结Outseta Piece 用手动 Webhook 触发器 Admin API 动作的组合覆盖了从账户/联系人/商机/任务/计划事件的实时响应到账户、订阅、发票、折扣、支持工单的全量操作面。理解它的三个关键支点即可高效使用连接域名 API Key API Secret 三元组鉴权头为Outseta key:secret保存连接时会自动打一次真实 API 校验触发每个触发器对应一个实体域在 Outseta 的 Notifications 里逐事件把同一 Webhook URL 配进去eventSubTypes选项与后台菜单 1:1 镜像动作45 个具名动作 通用 Custom API Call 兜底底层统一走带按页翻页分页与items/Items兼容处理的OutsetaClient。README 记录的 v0.1.0 只是起点当前包版本 0.2.3源码注释中沉淀的分页语义、fields*规则、CancelationReason拼写、PUT 前展开信封数组等细节都是与 Outseta Admin API 实战磨合的产物——这些文件client.ts、custom-properties.ts、dropdowns.ts本身就是对接 Outseta API 时非常值得细读的参考实现。【免费下载链接】activepiecesAI Agents MCPs AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows AI Agents • MCPs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/ac/activepieces创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考