SuperAPI AI 工具集

ringcentral-webhooks

编程与开发

查看项目

更新于 10-16 05:52

技能介绍

用途:接收并验证 RingCentral Webhook,适用于设置 RingCentral 订阅、完成 Validation-Token 握手、用 Verification-Token 校验通知,以及处理 message-store、presence、telephony/sessions 等事件,也涉及订阅被拉黑的排查。

验证机制:RingCentral 不使用 HMAC 签名,也不遵循 Standard Webhooks 规范,真实性依靠两种机制。其一为强制的 Validation-Token 握手:创建或续订订阅时,RingCentral 发送携带 Validation-Token 请求头的请求,处理程序须在几秒内把该值原样回写到 Validation-Token 响应头并返回 200,无需正文。其二为可选的 Verification-Token:在订阅上设置任意 verificationToken 字符串,RingCentral 会在每条通知上以 Verification-Token 头发送,建议用定时安全比较拒绝伪造请求。示例代码提供 Node 的 crypto.timingSafeEqual 与 Python 的 hmac.compare_digest 片段。

事件识别:事件由事件过滤器(API 资源路径)在通知的 event 字段中标识,而非短名称。常见过滤器包括 message-store(新消息:短信、语音留言、传真)、message-store/instant?type=SMS(即时入站短信)、presence(分机在线状态变化)、telephony/sessions(通话生命周期)、extension 级 telephony/sessions,以及 extension(分机创建/更新/删除)。

环境与本地开发:可选共享密钥通过环境变量 RINGCENTRAL_VERIFICATION_TOKEN 设置,并在创建订阅时作为 verificationToken 传入。本地开发可用 npx hookdeck-cli listen 3000 ringcentral --path /webhooks/ringcentral 启动隧道,地址须为 HTTPS,由隧道提供。

参考资料与限制:提供 references/overview.md、references/setup.md、references/verification.md 及 examples/express、nextjs、fastapi 完整示例。使用该技能时需在生成文件顶部添加指定注释。建议同时安装 webhook-handler-patterns 技能,涵盖处理顺序、幂等、错误处理与重试逻辑。其他细节如具体收费与价格暂未提供。