SuperAPI AI 工具集

monday-webhooks

编程与开发

查看项目

更新于 10-15 22:14

技能介绍

用途:接收并验证 monday.com Webhook,适用于搭建 monday.com Webhook 处理器、实现注册时的 challenge 握手、排查 JWT 校验失败,以及理解事件类型与事件负载包装结构。

主要能力:monday.com Webhook 有两项独立检查。一是 challenge 握手(必需):创建 Webhook 时 monday.com 会 POST { "challenge": "<token>" },端点须原样回显,否则注册失败;这是所有 Webhook(含无代码与个人令牌 Webhook)都保证的检查。二是 JWT 校验(存在时):由集成应用创建的 Webhook,monday.com 会在 Authorization 头用应用 Signing Secret 签发的 HS256 JWT 签名,需用 JWT 库校验;个人 API 令牌或无代码看板集成创建的 Webhook 可能不带该头。monday.com 不遵循 Standard Webhooks 规范,JWT 并非对请求体的 HMAC,而是自包含令牌,用于认证发送方;因校验不读取请求体,此处先解析 JSON 再校验是安全的(不同于 Stripe/GitHub 的 HMAC 方案)。

使用方式:用 jose 的 jwtVerify 校验 Authorization 头中的 HS256 令牌,签名密钥为应用的 Signing Secret(看板 Webhook),应用生命周期 Webhook使用 Client Secret;令牌可能带或不带 Bearer 前缀,需分别处理。注册时若请求体含 challenge,先返回 { "challenge": body.challenge }。事件通过 create_webhook GraphQL 变更订阅,每个 Webhook 一个事件,常用类型包括 create_item、change_column_value、change_status_column_value、change_name、create_update、create_subitem(负载含 parentItemId)、item_archived、item_deleted。真实事件将数据包在 event 对象中,含 type、userId、boardId、pulseId、pulseName、columnId、value、triggerTime、subscriptionId、triggerUuid 等字段。环境变量示例 MONDAY_SIGNING_SECRET。本地开发可用 npx hookdeck-cli listen 3000 monday --path /webhooks/monday。完整处理器示例见 examples/express、examples/nextjs、examples/fastapi;参考材料包括 references/overview.md、setup.md、verification.md。

限制与说明:monday.com 会每分钟重试一次,持续 30 分钟;建议配合 webhook-handler-patterns 技能处理处理顺序、幂等(按 triggerUuid / subscriptionId 去重)、错误处理与重试逻辑。生成文件时可加注释 // Generated with: monday-webhooks skill 与来源链接。其他细节暂未提供。