Skip to Content
goldflow.cc 文档
管理接口通知

通知 Webhook 协议

用户余额不足通知的 JSON 请求体、金额单位、签名验证和企业微信机器人格式。

在 个人资料 → 通知配置 中开启余额不足提醒,将通知方式设为 Webhook,填写接收 URL,并按需配置 Secret。达到通知条件后,goldflow.cc 向你的接收地址发送 HTTP 请求。

本文说明用户通知 Webhook,重点介绍钱包和订阅额度的余额不足提醒。系统全局 Webhook、图片和视频任务回调使用各自的协议。

请求方式

项目说明
方法POST
URL用户配置的 Webhook URL,建议使用 HTTPS
Content-Typeapplication/json
X-Webhook-Signature配置 Secret 时发送,值为请求体的 HMAC-SHA256 十六进制签名
超时发送器设置 30 秒请求超时

普通 Webhook 请求体

例如自定义阈值为 $5,钱包剩余余额为 $2.50,且服务端配置为美元显示时,请求体如下。域名和时间戳均为示例。

{
  "type": "quota_exceed",
  "title": "您的额度即将用尽",
  "content": "您的额度即将用尽,当前剩余额度为 $2.500000,为了不影响您的使用,请及时充值。<br/>充值链接:<a href='https://example.com/wallet'>https://example.com/wallet</a>",
  "values": [
    "您的额度即将用尽",
    "$2.500000",
    "https://example.com/wallet",
    "https://example.com/wallet"
  ],
  "timestamp": 1794441600
}
字段类型说明
typestring通知事件类型,见下表
titlestring通知标题
contentstring已替换模板占位符的正文,普通 Webhook 中可以包含 HTML 换行和链接
valuesarray,可省略模板参数,按原顺序保留;余额不足通知当前包含四个字符串
timestampinteger发送时的 Unix 秒级时间戳,不是毫秒时间戳,也不是事件唯一 ID

余额不足通知中的 values 使用从零开始的下标:

下标内容
values[0]提醒文案,例如 您的额度即将用尽
values[1]已格式化的剩余额度,例如 $2.500000
values[2]充值链接的地址
values[3]充值链接的显示文本,当前与地址相同

其他通知也可以复用普通 Webhook 的外层结构,但其 values 长度和含义由对应模板决定,不能统一按余额通知解析。

金额与阈值单位

values[1] 已经由后端换算并格式化,不是内部额度数值,不需要再除以 500000。在默认换算比例下,内部额度 1250000 对应 $2.50,美元显示字符串为 $2.500000,保留六位小数。这里的 $ 是全角美元符号。

具体格式由服务端额度显示配置决定:美元使用 $,人民币使用 ¥ 并应用配置汇率,自定义货币使用配置的符号和汇率;原始额度模式则返回额度数字字符串。不要仅凭阈值输入框的美元单位判断推送字符串一定使用美元。

用户界面的余额阈值以美元输入,保存时会换算回内部额度单位。配置接口中的 quota_warning_threshold 仍使用内部额度单位;默认 500000 单位等于 $1,实际比例以站点配置为准。界面单位的调整不会改变 Webhook 的既有金额格式。

当前请求体没有独立的 balance、threshold、currency 或 user_id 字段。values[1] 是显示字符串,不是 JSON 数值;钱包与订阅额度提醒也没有独立的结构化作用域字段。

余额通知事件

type含义
quota_exceed剩余额度大于零且低于用户自定义阈值
quota_exceed_usd_5未设置正数自定义阈值时,默认低于 $5 的金额预警
quota_exceed_insufficient剩余额度小于或等于零,额度已耗尽

钱包提醒标题为 您的额度即将用尽 或 您的额度已耗尽;订阅提醒标题为 您的订阅额度即将用尽 或 您的订阅额度已耗尽,事件类型相同。

通知还会受用户开关、去重和限流规则约束,不是每次低于阈值的请求都会推送。未设置正数自定义阈值时,如果钱包已有可靠的余额耗尽预测且有可用通知邮箱,早期提醒可能由预测邮件承担。余额预测、充值确认和公告通过邮件发送,不会因为选择 Webhook 而改用本协议。

Secret 与签名验证

配置 Secret 后,接收端可以用同一个 Secret 验证 X-Webhook-Signature:

signature = hex(HMAC-SHA256(secret, raw_request_body))

签名为 64 位小写十六进制字符串,没有 sha256= 前缀。必须使用收到的原始请求体字节验签,再解析 JSON;重新序列化可能改变空格、字段顺序或 HTML 的 Unicode 转义,导致验签失败。

Node.js 验签示例,rawBody 为读取到的原始 Buffer:

import { createHmac, timingSafeEqual } from 'node:crypto';

function verifyWebhook(rawBody, signature, secret) {
  if (!secret || typeof signature !== 'string' || !/^[a-f0-9]{64}$/.test(signature)) {
    return false;
  }

  const expected = createHmac('sha256', secret).update(rawBody).digest();
  const received = Buffer.from(signature, 'hex');
  return timingSafeEqual(expected, received);
}

没有配置 Secret 时,不发送该签名头。直连发送不附带 Authorization;通过 Worker 发送且配置 Secret 时,当前实现还会附带 Authorization: Bearer <secret>。统一接入时应验证签名头。

接收响应与重复处理

普通 Webhook 返回任意 2xx 状态即视为发送成功,不要求特定响应体;例如返回 204 No Content。非 2xx、连接错误或超时视为失败。

余额通知会记录发送状态并去重,失败后的再次尝试依赖后续通知检查。本协议没有投递 ID,也不承诺固定重试次数、顺序或恰好一次投递;接收端应能处理重复通知,不能仅用 timestamp 作为唯一键。

企业微信机器人

如果接收地址是 https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=...,发送器会自动使用企业微信 Markdown 格式,替换普通 Webhook 的整个请求体:

{
  "msgtype": "markdown",
  "markdown": {
    "content": "## 您的额度即将用尽\n\n您的额度即将用尽,当前剩余额度为 $2.500000,为了不影响您的使用,请及时充值。\n充值链接:[https://example.com/wallet](https://example.com/wallet)"
  }
}

该格式不携带普通请求体中的 type、values 或 timestamp。正文中的 HTML 换行和链接会转换为 Markdown,过长内容会按 UTF-8 字节限制截断。配置 Secret 时,签名针对最终发送的企业微信 JSON 请求体计算。

企业微信除了返回 2xx,响应 JSON 还必须包含 "errcode": 0 才算成功;错误码非零、缺少错误码或响应无法解析均视为失败。

On this page