通知 Webhook 协议
用户余额不足通知的 JSON 请求体、金额单位、签名验证和企业微信机器人格式。
在 个人资料 → 通知配置 中开启余额不足提醒,将通知方式设为 Webhook,填写接收 URL,并按需配置 Secret。达到通知条件后,goldflow.cc 向你的接收地址发送 HTTP 请求。
本文说明用户通知 Webhook,重点介绍钱包和订阅额度的余额不足提醒。系统全局 Webhook、图片和视频任务回调使用各自的协议。
请求方式
| 项目 | 说明 |
|---|---|
| 方法 | POST |
| URL | 用户配置的 Webhook URL,建议使用 HTTPS |
Content-Type | application/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
}| 字段 | 类型 | 说明 |
|---|---|---|
type | string | 通知事件类型,见下表 |
title | string | 通知标题 |
content | string | 已替换模板占位符的正文,普通 Webhook 中可以包含 HTML 换行和链接 |
values | array,可省略 | 模板参数,按原顺序保留;余额不足通知当前包含四个字符串 |
timestamp | integer | 发送时的 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 才算成功;错误码非零、缺少错误码或响应无法解析均视为失败。