Cal.diy × Make 集成实战指南从安装、API Key 到 Webhook 场景编排【免费下载链接】cal.diyScheduling infrastructure for absolutely everyone.项目地址: https://gitcode.com/GitHub_Trending/ca/cal.diyCal.diy 在应用商店中提供了 Make 自动化集成应用用户可以将「预订创建、预订删除、预订改期、会议结束」等事件通过 Webhook 实时推送到 MakeMake.com场景进而串联邮件通知、CRM、表格、消息应用等任意下游系统。本文以 Make 集成自述文档 为骨架结合仓库内 Make 应用源码 与 订阅调度实现完整讲解安装、密钥管理、invite_link 配置、场景创建、Connection 建立与 Webhook 删除并给出本地/自托管环境的 ngrok 方案。Make 集成是什么Make原名 Integromat是一款可视化工作流自动化平台。Cal.diy 的 Make 应用将 Cal.diy 的预订事件转化为 Make 场景的触发器并在应用内提供「List Bookings」模块用于拉取当前账号的预订记录。在仓库中的应用元数据 config.json 中可以看到该应用的注册信息{ name: Make, slug: make, type: make_automation, variant: automation, categories: [automation], publisher: aar2dee2, description: From tasks and workflows to apps and systems, build and automate anything in one powerful visual platform., isOAuth: false }要点type为make_automationvariant为automation归入automation分类说明它并非 OAuth 应用isOAuth: false而是通过 API Key 鉴权的自动化集成应用安装入口定义在 api/add.ts安装成功后会将用户重定向到/apps/make/setup页面完成后续配置应用官方描述见 DESCRIPTION.md可触发「预订创建、改期、取消、会议结束」四类工作流并可通过List Bookings模块获取全部预订描述中同时提示若遗失 API Key可随时在Make Setup 页面/apps/make/setup重新生成。第 1 步安装应用并生成 API Key打开 Cal.diy 的App Store搜索并安装Make应用安装后进入 Setup 页面点击Generate API key生成密钥并复制保存。从源码看API Key 与普通 Cal.diy API Key 同一套体系订阅相关的所有 API 端点都会调用findValidApiKey(apiKey, make)校验密钥见 addSubscription.ts校验失败统一返回401 { message: API key not valid }该校验工具位于 packages/app-store/_utils/findValidApiKey.ts。因此密钥一旦遗失需要在 Setup 页面重新生成后同步更新 Make 中的 Connection。第 2 步配置 invite_link安装应用后需要以管理员身份访问 Cal.diy 后台的/admin/apps/automation为 Make 设置invite_link值为 Make 官方的应用邀请链接https://www.make.com/en/hq/app-invitation/6cb2772b61966508dd8f414ba3b44510该配置项不是可选项。在 zod.ts 中应用的密钥 Schema 强制要求export const appKeysSchema z.object({ invite_link: z.string().min(1), });即invite_link必须是长度 ≥ 1 的字符串否则应用密钥校验无法通过。Setup 页面在服务端渲染时会通过 getServerSideProps 调用getAppKeysFromSlug(make)读取该值并将其以inviteLink属性的形式注入页面组件IMakeSetupProps用于引导用户接受邀请、跳转 Make 应用中心。配置顺序建议先完成本步再进入 Make 侧操作否则 Setup 页面拿不到有效的邀请链接。第 3 步在 Make 中创建场景若无 Make 账号先前往 Make 官网注册https://www.make.com/en/login登录后点击侧边栏的Scenarios场景然后点击Create a new scenario创建新场景在应用列表中搜索Cal.diy从以下触发器中选择其一Booking Created预订创建Booking Deleted预订删除Booking Rescheduled预订改期Meeting Ended会议结束这四种触发器与 Cal.diy 内部的 Webhook 事件枚举一一对应WebhookTriggerEvents中的BOOKING_CREATED、BOOKING_DELETED、BOOKING_RESCHEDULED、MEETING_ENDED事件触发后 Cal.diy 会将预订负载以 Webhook 形式投递到 Make 场景中作为场景的输入数据。第 4 步创建 Connection连接在 Make 中配置触发器时需要创建一个Connection需要提供两项信息字段说明Cal 部署 URLbaseUrl你的 Cal.diy 部署地址例如https://cal.diy或自托管域名/ngrok 地址API Key第 1 步中生成的 Make 应用 API KeyConnection 只需创建一次之后创建的所有 Webhook 都可以复用同一个连接。连接的本质是一组凭据Make 侧保存部署 URL 与 API Key后续所有订阅管理请求创建、删除、查询都会携带该 API Key 访问 Cal.diy 的订阅 API。例如创建订阅的端点 addSubscription.tsPOST请求Query 参数携带apiKeyBody 携带subscriberUrlMake 的回调地址与triggerEvent触发事件服务端先用findValidApiKey校验密钥再调用 scheduleTrigger.ts 中的addSubscription在 Prisma 的Webhook表中写入一条记录eventTriggers、subscriberUrl、appId: make、active: true。同理删除订阅使用 deleteSubscription.ts 的DELETE请求携带apiKey与id查询用户信息使用 me.ts 的GET请求获取预订列表使用 listBookings.ts 的GET请求——该端点内部调用listBookings最多返回最近 3 条预订take: 3按id倒序无预订时返回404并提示先创建一条预订。底层实现细节订阅如何落地从 scheduleTrigger.ts 可以进一步理解订阅的生命周期addSubscription以v4()生成 Webhook 记录 ID写入userId或teamId取决于 API Key 归属并把appId标记为make若触发器为MEETING_ENDED/MEETING_STARTED还会为「已存在的未来预订」补调度定时任务scheduleTrigger确保已排期的会议也能按时触发通知deleteSubscription按appId webhookId精确删除 Webhook 记录删除失败会记录错误日志listBookings按userId/teamId过滤预订返回uid、title、startTime、endTime、location、status、参与者与事件类型等字段供 Make 场景直接消费。这也是「在 Make 中删除 Webhook」与「在 Cal 侧删除订阅」的对应关系删除操作最终落在 Cal.diy 的 Webhook 记录上。第 5 步配置并管理 Webhook在 Make 中为选定的事件完成 Webhook 配置选择 Connection、指定要监听的预订/事件类型保存并启用场景后Cal.diy 对应事件发生时会实时推送数据删除 Webhook进入 Make 左侧边栏的Webhooks选中要删除的 Webhook点击delete即可。这会触发 Cal.diy 侧的deleteSubscription接口同步移除订阅记录。本地开发与自托管Localhost / Self-hosting限制Make 不能使用localhost作为 API 端点的 baseUrl。若你在本地或内网环境运行 Cal.diy需要使用公网隧道暴露服务官方文档给出的推荐方案是 ngrok在 ngrok 官网注册账号并下载 ngrok启动一个指向本地 Cal.diy 服务的隧道例如ngrok http 3000将终端输出的Forwarding公网地址如https://xxxx.ngrok-free.app作为 API 端点的 baseUrl在 Make 创建Connection时把 Cal 部署 URL 填为这个 ngrok 地址而不是http://localhost:3000。注意ngrok 免费版的公网地址会变化一旦地址变更需要回到 Make 更新 Connection 中的 baseUrl否则 Webhook 投递将失败。常见问题速查问题处理方式找不到 Cal.diy 触发器确认/admin/apps/automation中的invite_link已正确配置且已接受邀请Connection 一直校验失败检查 API Key 是否复制完整cal_前缀开头确认 baseUrl 可公网访问、不是 localhost收不到事件确认 Webhook 已启用、场景处于 ON 状态并检查 Cal 部署日志中订阅是否创建成功想换绑事件在 Make 的Webhooks中删除旧 Webhook 后重新按新事件创建查不到预订列表List Bookings仅返回最近 3 条预订若返回 404先创建一条新预订再查询相关源码索引应用元数据packages/app-store/make/config.json应用入口与模块导出packages/app-store/make/index.ts安装处理重定向到 Setup 页packages/app-store/make/api/add.ts密钥 Schemainvite_link 必填packages/app-store/make/zod.tsSetup 页服务端逻辑packages/app-store/make/pages/setup/_getServerSideProps.tsx订阅 API 端点addSubscription.ts、deleteSubscription.ts、listBookings.ts、me.ts订阅底层实现packages/features/webhooks/lib/scheduleTrigger.ts【免费下载链接】cal.diyScheduling infrastructure for absolutely everyone.项目地址: https://gitcode.com/GitHub_Trending/ca/cal.diy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考