Notification Webhook Protocol
JSON payloads, amount units, signature verification, and WeCom robot formatting for user low-balance notifications.
Open Profile → Notification Settings, enable low-balance alerts, select Webhook, enter a receiving URL, and optionally configure a Secret. goldflow.cc sends an HTTP request to that URL when an alert is due.
This guide covers user notification webhooks, with wallet and subscription low-balance alerts as the main example. Global system webhooks and image or video task callbacks use their own protocols.
HTTP request
| Item | Description |
|---|---|
| Method | POST |
| URL | The configured Webhook URL; HTTPS is recommended |
Content-Type | application/json |
X-Webhook-Signature | Sent when a Secret is configured; the hexadecimal HMAC-SHA256 signature of the request body |
| Timeout | The sender sets a 30-second request timeout |
Generic webhook payload
For a custom threshold of $5, a wallet balance of $2.50, and a server configured to display USD, the payload looks like this. The domain and timestamp are examples. The notification text below matches the current Chinese alert template.
{
"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
}| Field | Type | Description |
|---|---|---|
type | string | Notification event type; see the event table below |
title | string | Notification title |
content | string | The message after template substitution; generic webhook content can include HTML line breaks and links |
values | array, optional | Template arguments in their original order; low-balance alerts currently contain four strings |
timestamp | integer | Unix timestamp in seconds at send time, not milliseconds or a unique event ID |
Low-balance alerts use these zero-based array positions:
| Position | Value |
|---|---|
values[0] | Alert text, such as 您的额度即将用尽 (your quota is running low) |
values[1] | The formatted remaining quota, such as $2.500000 |
values[2] | Top-up URL |
values[3] | Top-up link text, currently identical to the URL |
Other notification types can use the same generic envelope, but the length and meaning of values depend on their templates. Do not apply the low-balance positions to every notification.
Amount and threshold units
values[1] has already been converted and formatted by the backend. It is not a raw quota number and must not be divided by 500000 again. At the default conversion rate, 1250000 internal quota units equal $2.50; the USD display string is $2.500000, with six decimal places. The $ character is a full-width dollar sign.
The server's quota display configuration determines the format: USD uses $, CNY uses ¥ and the configured exchange rate, and a custom currency uses its configured symbol and rate. Raw quota mode returns a quota number as a string. A USD threshold input does not guarantee that the notification amount is formatted in USD.
The user interface accepts a balance threshold in USD and converts it back to internal quota units when saving. The settings API field quota_warning_threshold still uses internal quota units. The default rate is 500000 units per $1; the actual rate follows the site configuration. Changing the input unit does not change the existing webhook amount format.
The payload has no separate balance, threshold, currency, or user_id fields. values[1] is a display string, not a JSON number. Wallet and subscription alerts also have no separate structured scope field.
Low-balance event types
type | Meaning |
|---|---|
quota_exceed | The remaining quota is positive and below the user's custom threshold |
quota_exceed_usd_5 | The default alert below $5 when no positive custom threshold is configured |
quota_exceed_insufficient | The remaining quota is zero or negative; the quota is depleted |
Wallet titles are 您的额度即将用尽 (quota running low) or 您的额度已耗尽 (quota depleted). Subscription titles are 您的订阅额度即将用尽 or 您的订阅额度已耗尽. They share the same event types.
Delivery is also subject to user preferences, deduplication, and rate limits. A request below the threshold does not always produce a webhook. Without a positive custom threshold, a reliable wallet balance forecast and an available notification email can move the early warning to a forecast email. Balance forecasts, top-up confirmations, and announcements remain email notifications when Webhook is selected.
Secret and signature verification
When a Secret is configured, verify X-Webhook-Signature using that same Secret:
signature = hex(HMAC-SHA256(secret, raw_request_body))The signature contains 64 lowercase hexadecimal characters, with no sha256= prefix. Verify the original request body bytes before parsing JSON. Re-serializing JSON can change whitespace, field order, or Unicode escapes for HTML and invalidate the signature.
Node.js example, where rawBody is the original request 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);
}Without a Secret, no signature header is sent. Direct delivery does not add an Authorization header. Worker delivery with a Secret currently also adds Authorization: Bearer <secret>. Use the signature header for verification across both delivery modes.
Responses and duplicate handling
For a generic webhook, any 2xx HTTP response counts as success, with no required response body. For example, return 204 No Content. Non-2xx responses, connection errors, and timeouts count as failures.
Balance notifications record delivery state and deduplicate alerts. Subsequent attempts after a failure depend on later notification checks. The protocol provides no delivery ID and promises no fixed retry count, ordering, or exactly-once delivery. Receivers should tolerate duplicate notifications and must not treat timestamp alone as a unique key.
WeCom robots
For a URL matching https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=..., the sender automatically replaces the generic payload with a WeCom Markdown payload:
{
"msgtype": "markdown",
"markdown": {
"content": "## 您的额度即将用尽\n\n您的额度即将用尽,当前剩余额度为 $2.500000,为了不影响您的使用,请及时充值。\n充值链接:[https://example.com/wallet](https://example.com/wallet)"
}
}This payload does not include the generic type, values, or timestamp fields. HTML line breaks and links are converted to Markdown, and long content is truncated at a UTF-8 byte limit. If a Secret is configured, the signature is calculated over the final WeCom JSON body.
In addition to a 2xx status, WeCom must return a JSON body containing "errcode": 0. A nonzero code, a missing code, or an unparseable response counts as failure.