使用 corsair-dev/monday 为 AI Agent 接入 Monday.com端点、认证与 Webhook 完整指南【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsair本指南以corsair-dev/monday插件为核心讲解如何在 Corsair 应用中把用户的 Monday.com 账户安全地暴露给 AI Agent。你将掌握插件的安装方式、26 个 GraphQL 端点的操作语义与风险分级、API Key 认证的多租户隔离机制以及 4 类 Webhook 事件的签名校验、租户匹配与实时数据同步的完整实现最终能在自己的 Agent 应用里直接落地这一套用户连接自己应用的集成方案。插件概览corsair-dev/monday是 Corsair 官方维护的 Monday.com 集成插件包目录见 packages/monday。Corsair 的整体定位是Connect your users to their apps——让 AI Agent 以受控方式操作终端用户自己账户中的第三方应用数据。本插件正是这一理念在 Monday.com 上的落地开发者定义一组语义化操作如列出看板创建条目更改列值Corsair 负责认证凭据的多租户存取、请求的权限校验与事件回传Agent 只需调用这些语义化端点即可。从 packages/monday/index.ts 可以看出插件的核心由三部分组成端点树endpoints按资源域boards / items / groups / columns / updates / users / workspaces / webhooks组织的 26 个操作认证配置authConfig基于api_key的凭据模型支持按accountId做租户隔离Webhook 绑定webhooks内置 4 类事件处理器负责签名校验、租户匹配与数据落库。插件通过monday()工厂函数创建返回一个符合CorsairPlugin接口的插件对象可无缝接入 Corsair 的插件注册体系。安装在 Corsair 项目中使用 pnpm 安装pnpm add corsair-dev/monday根据 packages/monday/package.json该包的 peerDependencies 为corsair0.1.0Corsair 核心运行时zod^4.1.13用于端点输入输出与 Webhook 载荷的运行时校验。插件以 ESM 形式发布exports同时提供dev-source直接指向源码index.ts便于开发期调试与编译后的dist产物。在应用中的最小用法import { monday } from corsair-dev/monday; const mondayPlugin monday({ // 可选的显式 API Key通常不配置交给 Corsair 按租户管理 // key: your-monday-api-key, // 可选Webhook 签名密钥配置后 Webhook 请求优先使用它验签 // webhookSecret: your-signing-secret, });创建后的插件对象包含id: monday、认证配置、端点树、Webhook 树、端点元数据风险等级与描述、输入输出 Zod Schema 以及错误处理器直接交给 Corsair 运行时绑定即可。Endpoints26 个语义化操作插件把 Monday.com 的 GraphQL API 封装为 26 个带语义的操作每个操作都有稳定的Operation ID形如monday.api.boards.list、风险等级read/write/destructive与人类可读描述。完整清单见下表与 packages/monday/README.md 及 index.ts 中的 mondayEndpointMeta 一致OperationOperation IDRiskDescriptionboards.archivemonday.api.boards.archivewriteArchive a boardboards.createmonday.api.boards.createwriteCreate a new boardboards.deletemonday.api.boards.deletedestructivePermanently delete a boardboards.duplicatemonday.api.boards.duplicatewriteDuplicate a boardboards.getmonday.api.boards.getreadGet a board by ID with groups and columnsboards.listmonday.api.boards.listreadList all boardsboards.updatemonday.api.boards.updatewriteUpdate a board attributecolumns.changeValuemonday.api.columns.changeValuewriteChange a column value on an itemcolumns.createmonday.api.columns.createwriteCreate a new column in a boardcolumns.listmonday.api.columns.listreadList all columns in a boardgroups.createmonday.api.groups.createwriteCreate a new group in a boardgroups.deletemonday.api.groups.deletedestructiveDelete a group from a boardgroups.listmonday.api.groups.listreadList all groups in a boardgroups.updatemonday.api.groups.updatewriteUpdate a group attributeitems.archivemonday.api.items.archivewriteArchive an itemitems.createmonday.api.items.createwriteCreate a new item in a boarditems.deletemonday.api.items.deletedestructivePermanently delete an itemitems.getmonday.api.items.getreadGet an item by ID with column valuesitems.listmonday.api.items.listreadList items in a boarditems.movemonday.api.items.movewriteMove an item to a different groupitems.updatemonday.api.items.updatewriteUpdate a column value on an itemupdates.createmonday.api.updates.createwriteCreate an update (comment) on an itemupdates.deletemonday.api.updates.deletedestructiveDelete an update (comment)updates.listmonday.api.updates.listreadList updates (comments) on an itemusers.getmonday.api.users.getreadGet a user by IDusers.listmonday.api.users.listreadList all users in the accountwebhooks.createmonday.api.webhooks.createwriteSubscribe to a board event via webhookwebhooks.deletemonday.api.webhooks.deletedestructiveUnsubscribe a webhook by IDwebhooks.listmonday.api.webhooks.listreadList all webhooks for a boardworkspaces.listmonday.api.workspaces.listreadList all workspaces风险等级由 index.ts 中的mondayEndpointMeta定义并强类型校验satisfies RequiredPluginEndpointMeta可被 Corsair 的权限系统消费——例如默认拒绝destructive操作、write操作需要显式授权实现Agent 只读、人类确认后才可写删的治理模型。端点树结构与类型安全端点按资源域组织成嵌套树见 index.ts 的mondayEndpointsNested{ boards: { list, get, create, update, archive, delete, duplicate }, items: { list, get, create, update, move, archive, delete }, groups: { list, create, update, delete }, columns: { list, create, changeValue }, updates: { list, create, delete }, users: { list, get }, workspaces:{ list }, webhooks: { list, create, delete }, }每个端点的输入、输出类型与运行时 Schema 都集中在 packages/monday/endpoints/types.ts。所有端点均满足输入参数齐全且可选的字段都有默认行为、输出对象统一id: string、Zod Schema 采用.loose()宽容解析Monday 返回的多余字段不会被丢弃避免版本演进导致校验失败。关键端点与参数详解以下端点参数均来自 endpoints/types.ts 的 Input Schemas可直接作为调用契约使用。boards.list / boards.get / boards.create// 列看板分页 过滤 排序 { limit?: number, page?: number, workspace_ids?: number[], board_kind?: public | private | share, state?: active | archived | deleted | all, order_by?: created_at | used_at } // 按 ID 取看板含 groups 与 columns 详情 { board_id: string } // 新建看板board_kind 默认 public可选 workspace_id / template_id { board_name: string, board_kind?: public | private | share, workspace_id?: number, template_id?: number }boards.update / boards.duplicate// 更新看板属性board_attribute 仅限 name / description / communication { board_id: string, board_attribute: name | description | communication, new_value: string } // 复制看板duplicate_type 控制复制深度 { board_id: string, duplicate_type?: duplicate_board_with_structure | duplicate_board_with_pulses | duplicate_board_with_pulses_and_updates, board_name?: string, workspace_id?: number }items.list / items.create / items.update / items.move// 列条目items_page 游标分页 { board_id: string, limit?: number, cursor?: string } // 新建条目可选 group_id 与 column_valuesJSON 字符串 { board_id: string, item_name: string, group_id?: string, column_values?: string } // 更新条目列值value 为 Monday 列值的 JSON 字符串 { board_id: string, item_id: string, column_id: string, value: string } // 移动条目到其他分组 { item_id: string, group_id: string }groups / columns / updates// 分组创建可指定 position更新支持 title/color/position/相对位置 { board_id: string, group_name: string, position?: string } { board_id: string, group_id: string, group_attribute: title | color | position | relative_position_before | relative_position_after, new_value: string } // 列创建时 column_type 与 description 可选changeValue 改条目列值 { board_id: string, title: string, column_type?: string, description?: string } { board_id: string, item_id: string, column_id: string, value: string } // 更新评论create 需要 item_id 与 bodydelete 按 update_id { item_id: string, body: string } { update_id: string }users / workspaces / webhooks// 用户列表kind 过滤 guest 等 { limit?: number, page?: number, kind?: all | non_guests | guests | non_pending } // 工作区kind 为 open/closedstate 为 active/deleted/all { limit?: number, page?: number, kind?: open | closed, state?: active | deleted | all } // Webhook 订阅event 覆盖 11 种 Monday 事件config 为 JSON 字符串如监听指定列 { board_id: string, url: string, event: change_column_value | change_specific_column_value | change_status_column_value | create_item | create_update | delete_update | item_archived | item_deleted | item_moved_to_board | item_restored | when_date_arrived, config?: string }底层实现GraphQL 请求与限流所有端点最终都通过 packages/monday/client.ts 中的makeMondayRequest()与 Monday GraphQL API 通信固定请求基址https://api.monday.comPOST 到/v2Body 为{ query, variables }Content-Type: application/json认证头Authorization: apiKeyMonday 的 API Key 认证约定直接以 token 值作为请求头无Bearer前缀限流与重试内置RateLimitConfig见 client.ts开启限流、最多重试 3 次、初始退避 1s、指数退避倍数 2并读取retry-after、x-ratelimit-reset、x-ratelimit-remaining、x-ratelimit-limit响应头自适应等待错误处理GraphQL 响应中的errors数组会被聚合抛出为MondayAPIError消息为各错误 message 的逗号拼接Corsair 侧再经由 error-handlers.ts 统一映射。每个端点执行成功后都会调用logEventFromContext(ctx, monday.domain.op, ...)记录事件例如monday.boards.list、monday.items.create便于后续审计与可观测性。AuthAPI Key 认证与多租户凭据管理插件的认证方式为API key。根据 index.ts 的mondayAuthConfigexport const mondayAuthConfig { api_key: { account: [accountId] as const, }, } as const satisfies PluginAuthConfig;含义如下每个租户终端用户的 Monday 账户保存自己的 API Key凭据按accountId维度隔离account键即同一应用可以为不同 Monday 账户各自保存独立 Key实现多租户Corsair prompts your tenant for credentials on first use当 Agent 首次调用端点时若当前租户尚未绑定凭据Corsair 会向该租户发起凭据录入提示而不是让开发者集中保管所有用户的 Key。Key 解析优先级keyBuilder按调用来源解析密钥Webhook 请求若插件配置了webhookSecret直接使用该固定密钥验签否则从ctx.keys.get_webhook_signature()读取租户级 Webhook 签名密钥缺失时抛出[auth-missing:monday:webhook_signature]端点请求若插件显式配置了options.key全局 API Key使用之否则走ctx.keys.get_api_key()按租户取 Key均缺失时抛出AuthMissingError(monday, api_key)。这种全局 Key 兜底 租户 Key 优先的设计让开发者可以在私有化部署时用一把服务账号 Key而在 SaaS 多租户场景下让每个用户持有自己的 Key。Webhooks4 类事件与安全校验插件内置4 个 Webhook 处理器对应 Monday 看板/集成 Webhook 最常用的事件类型README 中 Handles 4 webhook events详见 packages/monday/webhooks/index.tsWebhook匹配事件类型行为challenge请求体含challenge字段原样回显challenge完成 Monday 的订阅验证握手itemCreatedevent.type create_pulse校验签名后将条目 upsert 进 Corsair 数据库返回corsairEntityIdcolumnValueChangedevent.type change_column_value校验签名后记录事件statusChangedevent.type change_status_column_value校验签名后记录事件Webhook 树结构index.ts 的mondayWebhooksNested为{ verification: { challenge }, items: { itemCreated }, columns: { columnValueChanged }, status: { statusChanged }, }事件载荷类型事件载荷 Schema 定义在 packages/monday/webhooks/types.ts。所有事件共享基础字段userId、boardId、pulseId、pulseName、groupId、triggerTime等并各自扩展itemCreatedevent.type固定为create_pulsecolumnValueChangedevent.type为change_column_value额外携带columnId、columnType、columnTitle、value与previousValue列值为多态 JSON用z.unknown()宽容建模statusChangedevent.type为change_status_column_value字段与列值变更类似challenge仅challenge: string。签名校验HS256 JWTMonday 的看板/集成 Webhook 会把HS256 JWT 放在Authorization头用 App 的 Signing Secret 签名而非常见的 body HMAC。verifyMondayWebhookSignature()webhooks/types.ts的实现要点从Authorization头提取 token兼容Bearer前缀大小写不敏感拆解 JWT 三段校验header.alg HS256用 secret 对header.payload计算 HMAC-SHA256与签名段做timingSafeEqual常量时间比较防时序侧信道校验exp过期时间。校验失败时返回 401 与具体错误信息见 item-created.ts 的 handler。代码注释特别强调Monday 的签名是JWT 放入 Authorization 头不是把请求体做 HMAC——如果按 body HMAC 方式校验会错误地拒绝全部真实流量。集成其他平台 Webhook 时务必先确认签名协议。租户匹配与数据落库租户匹配matchMondayTenantWebhook()webhooks/tenant-matcher.ts优先从请求体顶层accountId取否则解析 JWT payload 中的accountId返回{ linkType: accountId, externalId: accountId }供 Corsair 路由到对应租户challenge 握手请求不含accountId会被跳过租户解析。数据同步itemCreated处理器在ctx.db.items存在时用upsertByEntityId(event.pulseId, {...})把 Monday 条目落库含board_id、group_id、created_at、creator_id并返回生成的corsairEntityId打通Monday 事件 → Corsair 实体的映射Agent 后续可直接按内部 ID 引用该条目。事件记录四个处理器均调用logEventFromContext记录monday.webhook.*事件便于审计与重放排查。Webhook 请求匹配插件级匹配器pluginWebhookMatcherindex.ts判定请求头含x-monday-signature或authorization或请求体含challenge字符串 /event对象时即视为 Monday Webhook 流量兼容未配置 Signing Secret 时 Monday 发送的无认证头请求。参考与许可插件类型与更多示例可查阅仓库内 docs/plugins/monday 下的插件文档含 overview / setup / 使用示例或直接阅读源码 packages/monday端点的输入输出契约以 packages/monday/endpoints/types.ts 为权威来源Webhook 载荷与签名实现见 packages/monday/webhooks/types.ts 与 packages/monday/webhooks/tenant-matcher.ts自动化测试覆盖可参考 packages/monday/api.test.ts 与 packages/monday/webhooks/webhooks.test.ts许可证Apache-2.0。【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsair创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考