开发者:API 密钥与 Webhook

如果你想把 NextCLi 集成进自己的系统,可以用账号 API Key 调用平台接口,并用 Webhook 接收资源与账单事件。本文面向开发者。

账号 API Key

API Key 让你在不使用账号密码登录的情况下,以程序方式访问平台接口:

• 进入「设置 → API 密钥」,创建一个新的 Key。
• 创建时请立即复制并妥善保存——出于安全,完整 Key 通常只显示一次。
• 在请求中通过约定的请求头(如 X-API-Key)携带该 Key 调用接口。
• 不再使用的 Key 请及时删除;怀疑泄露立即吊销并重建。

API 凭证:创建与管理你的 API Key

> API Key 等同于你的身份凭证,切勿写死在前端代码或提交到公开仓库。

Webhook

> 说明:Webhook 功能正在开发中,控制台入口目前显示「即将上线」。下面是启用后的用法,供提前了解。

Webhook 让平台在发生事件时主动回调你的服务(如资源状态变化、账单/充值事件):

• 进入「设置 → Webhook」,添加一个接收地址(你的 HTTPS 端点)。
• 选择你关心的事件类型。
• 平台会在事件发生时向该地址 POST 事件数据。

校验签名

为确认回调确实来自平台、且未被篡改,请校验每次回调的签名:

• 平台会在请求头带上签名;你的服务用约定的密钥按同样算法计算并比对。
• 比对不通过的请求应一律拒绝。
• 建议同时校验时间戳、对事件做幂等处理(同一事件可能重试投递,勿重复执行副作用)。

最佳实践

• 幂等:用事件 ID 去重,重复投递只处理一次。
• 快速响应:回调端点尽快返回 2xx,耗时逻辑异步处理,避免平台判定失败重试。
• 最小权限:为不同用途创建不同的 API Key,便于按需吊销。

常见问题

• Key 忘了怎么办? 无法找回完整 Key,请删除后重建。
• 收不到 Webhook? 确认地址可公网访问、返回 2xx,检查所选事件类型;平台失败会重试。
• 签名校验总失败? 确认使用了正确的密钥与算法,并对原始请求体(未改动)计算签名。

---

相关参考

• 认证与 API Key
• API 约定:Request ID、分页与错误
• Webhook 与事件(规划中)
• 凭据管理见:账户:注册、登录与安全