Skip to Content
goldflow.cc Docs
ManagementNotifications

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

ItemDescription
MethodPOST
URLThe configured Webhook URL; HTTPS is recommended
Content-Typeapplication/json
X-Webhook-SignatureSent when a Secret is configured; the hexadecimal HMAC-SHA256 signature of the request body
TimeoutThe 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
}
FieldTypeDescription
typestringNotification event type; see the event table below
titlestringNotification title
contentstringThe message after template substitution; generic webhook content can include HTML line breaks and links
valuesarray, optionalTemplate arguments in their original order; low-balance alerts currently contain four strings
timestampintegerUnix timestamp in seconds at send time, not milliseconds or a unique event ID

Low-balance alerts use these zero-based array positions:

PositionValue
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

typeMeaning
quota_exceedThe remaining quota is positive and below the user's custom threshold
quota_exceed_usd_5The default alert below $5 when no positive custom threshold is configured
quota_exceed_insufficientThe 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.

On this page