工作流自动化低代码AI 应用人工智能AI AgentMCP 服务后端前端【免费下载链接】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点击查看免费下载本篇技术指南聚焦 Activepieces 开源仓库中的 Ko-fi 集成组件activepieces/piece-ko-fi。Ko-fi 是一个面向创作者的支持平台本组件为其提供四类基于 Webhook 的触发器捐赠、订阅、委托、店铺订单使创作者可以在 Activepieces 中搭建收到打赏 → 自动发感谢信 / 记录到表格 / 推送通知等自动化流程。读完本文你将掌握该组件的认证配置方式、四类触发器的事件数据结构、Webhook 处理与校验原理以及如何本地构建这个 piece。组件概览Ko-fi piece 的能力边界Ko-fi 组件位于packages/pieces/community/ko-fi/其入口定义在 src/index.ts。核心声明如下export const koFi createPiece({ displayName: Ko-fi, description: Receive triggers for donations, subscriptions, commissions, and shop orders from Ko-fi., auth: koFiAuth, minimumSupportedRelease: 0.30.0, logoUrl: https://cdn.activepieces.com/pieces/ko-fi.png, authors: [zeiyre, sanket-a11y], categories: [PieceCategory.PAYMENT_PROCESSING], actions: [], triggers: [newDonation, newSubscription, newCommission, newShopOrder], });从声明可以看出该组件有四个明确的特征纯触发器组件triggers-onlyactions: []表示它不提供任何主动执行的动作action只负责把 Ko-fi 平台事件推入Activepieces 流程。后续的发邮件、写表格、发通知等动作需要搭配其他 piece 完成。业务分类归类为PieceCategory.PAYMENT_PROCESSING支付处理。该枚举定义在 packages/core/piece-types/src/lib/piece.ts 中包含COMMERCE、ACCOUNTING等 17 个类别PAYMENT_PROCESSING用于支付类集成。最低支持版本minimumSupportedRelease: 0.30.0即该 piece 要求 Activepieces 0.30.0 及以上版本。框架侧packages/pieces/framework/src/lib/piece.ts会在创建 piece 时校验该版本号若低于框架定义的下限会自动提升。四种 Webhook 触发器newDonation新捐赠、newSubscription新订阅、newCommission新委托、newShopOrder新店铺订单分别定义于 src/lib/triggers/ 下的四个独立文件。认证配置Webhook 验证令牌Verification TokenKo-fi 的 Webhook 不做 OAuth2也不依赖 API Key而是使用一个每创作者唯一的验证令牌Verification Token。认证定义见 src/lib/auth.tsexport const koFiAuth PieceAuth.SecretText({ displayName: Verification Token, description: Your Ko-fi webhook verification token. Find it in Ko-fi Dashboard Settings API/Webhooks Advanced Settings Webhook verification token., required: true, });获取位置Ko-fi 创作者后台 Dashboard → Settings → API/Webhooks → Advanced Settings → Webhook verification token。属性类型PieceAuth.SecretText即框架中的密文文本认证类型定义于 packages/pieces/framework/src/lib/property/authentication/secret-text-property.ts。在 Activepieces 的 UI 中它会以密码框形式输入、以密文存储并作为连接connection与流程解耦管理。用途该令牌并非用于调用 Ko-fi API而是校验入站 Webhook 请求是否真实来自 Ko-fi。四个触发器的run方法都会执行event.verification_token ! context.auth.secret_text的比对不匹配则直接丢弃事件返回空数组。四种 Webhook 触发器详解四个触发器全部采用TriggerStrategy.WEBHOOK策略。该枚举定义于 packages/core/piece-types/src/lib/trigger.tsWEBHOOK表示由平台监听一个公开 URL、收到第三方 HTTP 请求后触发流程而非轮询POLLING或平台内置应用订阅APP_WEBHOOK。触发器 1新捐赠New Donation定义文件src/lib/triggers/new-donation.ts触发时机一次性打赏/捐赠到账时触发单次 tip非订阅付款。其sampleData完整展示了事件负载结构{ message_id: 3a1fac0c-f960-4506-a60e-2e3f3d09e6e0, timestamp: 2026-04-24T19:15:00Z, type: Donation, is_public: true, from_name: Supporter Name, message: Thanks for the work you do!, amount: 5.00, url: https://ko-fi.com/Home/CoffeeShop?txid00000000-1111-2222-3333-444444444444, email: supporterexample.com, currency: USD, is_subscription_payment: false, is_first_subscription_payment: false, kofi_transaction_id: 00000000-1111-2222-3333-444444444444 }字段语义字段说明message_id事件唯一 ID可用于流程内的去重timestamp事件发生时间ISO 8601UTCtype事件类型捐赠为Donationis_public支持者是否同意公开显示from_name/email支持者昵称与邮箱message支持者附言amount/currency金额字符串形式与币种如USDurlKo-fi 交易详情页链接内含txidkofi_transaction_idKo-fi 侧的交易 IDis_subscription_payment/is_first_subscription_payment订阅相关标记单次捐赠下均为false注verification_token字段会出现在原始 Webhook 负载中但触发器在run中校验完成后会将其剔除const { verification_token: _omit, ...payload } event因此进入流程下游的数据中不包含令牌避免凭据泄露到日志或下游系统。触发器 2新订阅New Subscription定义文件src/lib/triggers/new-subscription.ts触发时机支持者首次支付订阅会员费时触发。与捐赠相比负载多一个tier_name字段会员档位名称sampleData 示例为tier_name: Gold Tier。该触发器有一个值得注意的业务过滤逻辑if (event.type ! Subscription) { return []; } if (event.is_first_subscription_payment ! true) { return []; }也就是说周期性续费付款不会触发该流程只有第一次订阅付款才会触发。这非常适合新会员加入 → 欢迎邮件 / 发放权益这类一次性动作避免每月续费时重复触发。从源码注释Fires when a supporter starts a new recurring membership ... only on the first subscription payment可以确认这一设计意图。触发器 3新委托New Commission定义文件src/lib/triggers/new-commission.ts触发时机支持者在 Ko-fi 上提交付费委托请求时触发。负载在捐赠字段基础上增加了shipping对象涉及实物交付时的收货信息{ shipping: { full_name: string, street_address: string, city: string, state_or_province: string, postal_code: string, country: string, country_code: string, telephone: string } }注意shipping的类型是... | null即可能为null纯数字/线上交付的委托无收货信息下游使用字段前应做空值处理。message字段在此场景下承载委托需求描述如 sampleData 中的 Please draw my cat in the style of a renaissance portrait.可直接用于创建任务单或工单。触发器 4新店铺订单New Shop Order定义文件src/lib/triggers/new-shop-order.ts触发时机支持者在 Ko-fi Shop 购买商品时触发。负载在捐赠字段基础上新增shop_items数组与shipping对象{ shop_items: [ { direct_link_code: a1b2c3d4e5, variation_name: Standard, quantity: 1 } ], shipping: null }shop_items中的每一项包含direct_link_code商品直达链接码、variation_name规格/变体名称如颜色尺寸、quantity数量。该触发器适合接单 → 发货处理 / 销售记账 / 客服通知类自动化。Webhook 处理机制与源码原理理解这四种触发器的运行机制是正确使用和排障的关键。它们的处理逻辑高度一致可归纳为四个步骤1. 载荷解析URL 编码表单中的 JSONKo-fi 以URL-encoded form-post方式向 Webhook URL 发送请求请求体中只有一个名为data的字段其值是被编码的 JSON 字符串。触发器的run方法先取context.payload.body再通过JSON.parse(body.data)还原事件对象async run(context): PromiseKoFiDonationEvent[] { const body context.payload.body as KoFiWebhookBody; if (typeof body?.data ! string) { return []; } let event: KoFiDonationEvent; try { event JSON.parse(body.data) as KoFiDonationEvent; } catch { return []; } ... }若data缺失或 JSON 解析失败触发器静默返回空数组流程不触发、不报错这是对非 Ko-fi 来源请求的第一道防线。2. 双重校验令牌 事件类型解析成功后依次校验if (event.verification_token ! context.auth.secret_text) { return []; } if (event.type ! Donation) { return []; }令牌不匹配 → 丢弃防止伪造请求触发流程type与触发器预期类型不符 → 丢弃例如把订阅事件送进捐赠触发器的 URL会被正确拦截。3. 输出净化剥离令牌字段const { verification_token: _omit, ...payload } event; return [payload as KoFiDonationEvent];最终只把不含令牌的业务字段返回给流程下游。4. 生命周期钩子手动配置的必然性四个触发器的onEnable与onDisable都是空操作async () { return; }源码注释给出了明确原因Ko-fi 没有提供注册/删除 Webhook URL 的 API因此 Activepieces 无法在启用流程时自动在 Ko-fi 后台创建 Webhook必须由用户在 Ko-fi Dashboard 中手动粘贴平台生成的 Webhook URL。这也是为什么每个触发器都通过Property.MarkDown渲染一段配置指引其中{{webhookUrl}}是平台在运行时填充的实际回调地址指引文案统一为To receive donation events, set up a webhook in your Ko-fi Dashboard: go to Settings API/Webhooks, paste the URL{{webhookUrl}}, and select the Donation event type.四个触发器仅末尾的 Donation / Subscription / Commission / Shop Order 事件类型不同。排障要点如果流程不触发优先检查 ① Ko-fi 后台的 Webhook URL 是否与 Activepieces 面板显示的一致② 事件类型是否勾选正确③ 连接的 Verification Token 是否与 Ko-fi 后台 Advanced Settings 中的令牌一致。由于run对校验失败是静默丢弃令牌错误往往表现为Webhook 测试成功但流程无运行记录。在 Activepieces 中使用 Ko-fi 触发器完整的接入步骤基于组件源码与框架行为归纳添加连接在 Activepieces 中新建 Ko-fi 连接把 Ko-fi Dashboard → Settings → API/Webhooks → Advanced Settings 中的 Webhook verification token 填入Verification Token字段并保存。新建流程选择 Ko-fi piece 下的任一触发器作为流程起点例如New Donation。复制回调 URL查看触发器配置面板中的说明卡片复制其中渲染出的{{webhookUrl}}实际地址。配置 Ko-fi 后台登录 Ko-fi Dashboard → Settings → API/Webhooks粘贴该 URL并勾选与触发器对应的事件类型Donation / Subscription / Commission / Shop Order。每个事件类型对应一个 URL即四类事件可以分别指向四个不同流程。搭建下游动作把触发器输出的字段amount、from_name、email、message、kofi_transaction_id、shop_items、shipping等接入邮件、表格、通知等动作。注意amount是字符串类型数值运算前需先转换。测试在 Ko-fi 后台使用发送测试 Webhook功能或真实打赏小额验证流程运行也可以在触发器上使用sampleData进行模拟测试——createTrigger在未提供test函数时默认返回sampleData作为测试结果见 packages/pieces/framework/src/lib/trigger/trigger.ts。本地构建与开发组件的 README.md 给出的构建命令为turbo run build --filteractivepieces/piece-ko-fi该命令通过 Turborepo 按包名过滤仅构建 Ko-fi 组件。执行的是 package.json 中定义的build脚本scripts: { build: tsc -p tsconfig.lib.json cp package.json dist/, bundle: node ../../../../dist/packages/cli/src/index.js pieces bundle, lint: eslint src/**/*.ts }build用tsconfig.lib.json编译 TypeScript并把package.json复制进dist/产物目录得到activepieces/piece-ko-fi当前版本0.0.5。bundle调用仓库内 CLI 打包 piece 为可分发产物pieces bundle。lint对src/**/*.ts运行 ESLint。该 piece 的运行时依赖为activepieces/pieces-common、activepieces/pieces-framework、activepieces/core-piece-types、activepieces/core-utils均为workspace:*内部链接源码引用的createTrigger、createPiece、Property、PieceAuth、TriggerStrategy都来自activepieces/pieces-framework。多语言与元数据设计组件在 src/i18n/ 下提供了translation.json及de、es、fr、ja、nl、pt、zh等语言文件覆盖 piece 描述、认证描述、触发器名称与配置指引文案的本地化。同时每个触发器还带有aiMetadata.description字段为 AI 辅助流程构建提供语义化的事件说明例如New Subscription的 AI 元数据明确指出该触发器仅在首次订阅付款时触发方便 AI 编排时正确选用。小结Ko-fi piece 是 Activepieces 中一个典型的Webhook 纯触发器集成通过 src/lib/auth.ts 的验证令牌做入站鉴权通过 src/lib/triggers/ 下四个触发器覆盖捐赠、订阅、委托、店铺订单四类创作者收入场景并在 src/index.ts 中统一注册。它的实现展示了第三方无 Webhook 管理 API 时手动配置 入站校验 静默丢弃的集成范式也提醒使用者在 Ko-fi 后台正确配置回调 URL 与事件类型、在连接中准确填入验证令牌是让流程稳定运行的前提。赞分享工作流自动化低代码AI 应用人工智能AI AgentMCP 服务后端前端【免费下载链接】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点击查看免费下载相关推荐Ever Gauzy Zapier 集成插件实战OAuth2 授权、Webhook 订阅与计时器自动化Ever Gauzy Zapier 集成插件实战OAuth2 授权、Webhook 订阅与计时器自动化 gauzy/plugin integration z后端前端企业应用MCP 服务Pixelfed商业模式创新订阅、捐赠与高级功能Pixelfed商业模式创新订阅、捐赠与高级功能 Pixelfed作为去中心化的照片分享平台其商业模式围绕用户主权与社区支持构建了独特的可持续发展路径。本文后端前端Activepieces Stripe 集成组件piece深度指南构建、认证、Action 与 Webhook 触发器全解析Activepieces Stripe 集成组件piece深度指南构建、认证、Action 与 Webhook 触发器全解析 Activepieces 内工作流自动化低代码AI 应用人工智能AI AgentMCP 服务后端前端上一篇DeepAudit 实战代码安全审计全自动指南下一篇MikroORM v3 到 v4 升级迁移完全指南Monorepo 拆分、EntityManager 重构与破坏性变更全解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
