SuperAPI AI 工具集

smartcar-webhooks

编程与开发

查看项目

更新于 10-16 05:52

技能介绍

该技能用于在服务端接收并校验 Smartcar Webhook,适用于搭建 Smartcar Webhook 处理器、调试 SC-Signature 校验失败、响应 VERIFY 挑战以及处理 VEHICLE_STATE 和 VEHICLE_ERROR 事件。

校验机制(核心):Smartcar 用 Application Management Token(AMT,来自 Smartcar Dashboard)对原始请求体做 HMAC-SHA256,并以十六进制放入 SC-Signature 头。创建 Webhook 时 Smartcar 会发送一次性 VERIFY 事件,需在 15 秒内用同一 AMT 对 data.challenge 做哈希并回传,否则 Webhook 不会激活。这是 Smartcar 自有方案,不是 Standard Webhooks 规范。

官方 SDK 提供两个辅助函数:hashChallenge/hash_challenge(对字符串做十六进制 HMAC)与 verifyPayload/verify_payload(比较请求头与请求体 HMAC)。Node 示例中,VERIFY 事件返回 smartcar.hashChallenge(AMT, event.data.challenge),数据事件用 smartcar.verifyPayload(AMT, req.headers['sc-signature'], event) 校验;Python(FastAPI)中 SDK 会对传入的原始 body 字符串做哈希,失败返回 401。

常见事件类型:VERIFY(Webhook 创建或从 Dashboard 重新验证时触发,用于回传哈希挑战以激活)、VEHICLE_STATE(被监控信号变化,如电量、里程表,用于同步车辆数据、告警、更新仪表盘)、VEHICLE_ERROR(Smartcar 获取订阅信号失败,用于暴露连接问题,恢复时会触发 state: "RESOLVED" 的后续事件)。旧版 v2 定时或 eventBased Webhook 已弃用。

环境变量只需 SMARTCAR_MANAGEMENT_TOKEN(Dashboard 的 AMT),它是校验 payload 和回答 VERIFY 挑战的唯一密钥。本地开发可用 npx hookdeck-cli listen 3000 smartcar --path /webhooks/smartcar 启动隧道。仓库内 references/ 提供概览、配置与校验细节,examples/ 提供 Express、Next.js、FastAPI 完整处理器;建议搭配 webhook-handler-patterns 技能处理幂等、重试与错误。使用生成文件时需注释来源。限制:具体部署与生产配置资料未完整给出,暂未提供。