通知设置 - WebHook 参数介绍

零度API 支持通过 WebHook 向您的服务器推送通知，例如账户余额不足预警等事件。

注意： 仅支持 POST 地址作为 WebHook 地址。

---

WebHook 请求格式

当触发事件时，我们将向您配置的 WebHook 地址发送 POST 请求：

curl -X POST 'https://example.com/webhook' \
  -H 'Content-Type: application/json' \
  -d '{"topic": "user_quota_too_low", "data": {"quota": 0.5}}'

---

支持的事件类型（topic）

topic	触发条件	说明
user_quota_too_low	账户余额低于阈值	data.quota 为当前剩余额度（单位：元）

---

配置 WebHook

1. 登录 api000.com 控制台
2. 进入「通知设置」页面
3. 填写您的 WebHook URL（必须是可公网访问的 HTTPS POST 接口）
4. 设置余额预警阈值
5. 保存并测试

---

示例：接收 WebHook 通知（Python Flask）

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route("/webhook", methods=["POST"])
def webhook():
    data = request.json
    topic = data.get("topic")
    
    if topic == "user_quota_too_low":
        quota = data["data"]["quota"]
        print(f"⚠️ 余额不足警告！当前余额：{quota} 元")
        # 在这里发送告警邮件、钉钉消息等
    
    return jsonify({"status": "ok"})

if __name__ == "__main__":
    app.run(port=5000)

---

示例：接收 WebHook 通知（Node.js Express）

const express = require("express");
const app = express();

app.use(express.json());

app.post("/webhook", (req, res) => {
  const { topic, data } = req.body;

  if (topic === "user_quota_too_low") {
    console.log(`⚠️ 余额不足！当前余额：${data.quota} 元`);
    // 发送告警通知...
  }

  res.json({ status: "ok" });
});

app.listen(5000);

---

最佳实践

• WebHook 接口应在 3 秒内返回 200 响应，否则可能被判定为超时
• 建议对 WebHook 请求做幂等处理（同一事件可能多次推送）
• 如需安全验证，可在 URL 中加入 token 参数：https://example.com/webhook?token=your_secret