Webhook 事件

Webhook 是可选的推送通道：无需轮询，TRONAgg 会在事件发生时向你的 URL POST 一个带签名的 JSON 事件。轮询（GET /order/{id}、GET /deposits）始终可用，不依赖任何 Webhook——只有想要推送时才需要配置。

在 Workspace → Notifications 或通过 POST /webhooks 创建。

投递格式

每次投递都是一个 HTTPS POST，包含一个事件：

POST https://your-service.example.com/tronagg/webhook

{
  "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "type": "order.status_changed",
  "created_at": "2026-07-12T10:30:00Z",
  "audience": "customer",
  "data": { }
}

字段	含义
id	事件唯一 id——按它去重。
type	事件类型，同时出现在 X-TronAgg-Event 请求头中。
created_at	事件发生时间（ISO-8601，UTC）。
audience	对你的 Webhook 恒为 customer。
data	事件专属负载——见事件目录。

请求头	值
Content-Type	application/json
X-TronAgg-Event	事件 type。
X-TronAgg-Delivery	投递 id，重试间保持不变。
X-TronAgg-Timestamp	签名时的 Unix 秒。
X-TronAgg-Signature	v1=<hex>——验证方法。

至少一次投递

请在几秒内返回 2xx，耗时逻辑放到请求路径之外。失败的投递会按退避策略重试，同一事件可能到达多次——按 id 去重。

验证签名

签名是用你的 Webhook signing secret（仅在创建时展示一次）对 "{timestamp}.{raw_body}" 做 HMAC-SHA256，hex 编码为 v1=<hex>。务必对原始请求字节计算、恒定时间比较，并拒绝时间戳过旧的投递：

verify.py

import hashlib, hmac

def verify(secret: str, timestamp: str, body: bytes, signature_header: str) -> bool:
    expected = hmac.new(
        secret.encode(), timestamp.encode() + b"." + body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"v1={expected}", signature_header)

JavaScript（Node）版本

verify.js

const crypto = require("node:crypto");

function verify(secret, timestamp, rawBody, signatureHeader) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.`)
    .update(rawBody) // 收到的原始字节 Buffer
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(`v1=${expected}`),
    Buffer.from(signatureHeader)
  );
}

事件

On 事件在通过 POST /webhooks 创建的 Webhook 上默认开启；Off 事件默认关闭——均可在 Workspace → Notifications 中按 Webhook 单独开关。

事件	触发时机	默认
order.status_changed	订单完结——COMPLETED 或 FAILED。	✅ On
balance.credited	充值或入账到达你的余额。	✅ On
autoenergy.delegated	AutoEnergy 覆盖了一笔转账。	✅ On
autoenergy.closed	AutoEnergy 订阅停止。	✅ On
autoenergy.activated	AutoEnergy 订阅生效。	— Off
balance.low	余额跌破你设置的阈值。	— Off
account.daily_summary	每日账户摘要。	— Off

order.status_changed

轮询 GET /order/{id} 的推送替代。订单进入终态时触发一次。

{
  "order_id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "status": "COMPLETED",
  "resource_type": "ENERGY",
  "resource_amount": "65000",
  "receiver_address": "TC7UXt7t2WLGbFasqvErydRQZ7bnGbQs",
  "total_price_sun": 3500000,
  "error_message": null
}

字段	含义
status	COMPLETED 或 FAILED（大写，与 API 一致）。
resource_amount	Energy 数量，字符串。
total_price_sun	实际扣费，单位 SUN。
error_message	仅当 status 为 FAILED 时有值。

balance.credited

{
  "entry_id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "entry_type": "deposit",
  "amount_sun": 100000000,
  "balance_sun": 250000000,
  "reference_id": "a1b2c3d4e5f6..."
}

字段	含义
amount_sun	入账金额（SUN）。
balance_sun	入账后的余额（SUN）。
entry_type	链上充值为 deposit。
reference_id	入账来源，例如充值交易。

autoenergy.delegated

已订阅地址上每覆盖一笔转账触发一次。

{
  "subscription_id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "address": "TC7UXt7t2WLGbFasqvErydRQZ7bnGbQs",
  "energy_class": "131k",
  "billed_sun": 2100000,
  "used_tx_id": "a1b2c3d4e5f6...",
  "tx_used_total": 5,
  "quota_max_tx": 100
}

字段	含义
energy_class	本笔转账覆盖的 Energy——65k 或 131k。
billed_sun	本笔计费（SUN）。
used_tx_id	消耗该 Energy 的转账。
tx_used_total / quota_max_tx	已覆盖笔数 / 配额（null = 不设上限）。

autoenergy.closed

订阅因任何原因停止时触发。

{
  "subscription_id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "address": "TC7UXt7t2WLGbFasqvErydRQZ7bnGbQs",
  "close_reason": "quota",
  "tx_used_total": 42
}

字段	含义
close_reason	停止原因——quota、expired、idle、insufficient_balance、manual 等，视为开放集合。
tx_used_total	该订阅累计覆盖的转账数。

autoenergy.activated

订阅在地址上生效时触发。

{
  "subscription_id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "address": "TC7UXt7t2WLGbFasqvErydRQZ7bnGbQs"
}

balance.low

余额跌破你启用时设置的阈值，每次穿越触发一次。

{
  "entry_id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "entry_type": "purchase",
  "amount_sun": -3500000,
  "balance_sun": 12000000,
  "reference_id": "a1b2c3d4e5f6...",
  "threshold_sun": 50000000
}

字段	含义
balance_sun	触发穿越的变动之后的余额（SUN）。
threshold_sun	你配置的阈值（SUN）。
amount_sun	该笔变动本身——扣费为负数。

account.daily_summary

{
  "date": "2026-07-23",
  "completed_orders": 12,
  "energy_received": "780000",
  "spent_sun": 42000000,
  "balance_sun": 250000000
}

字段	含义
completed_orders	当日完成的订单数。
energy_received	当日委托给你的 Energy 总量（字符串）。
spent_sun / balance_sun	当日支出 / 日终余额（SUN）。

测试你的端点

POST /webhooks/{id}/test 发送一个 notification.test 事件，签名方式与真实投递完全一致——用它端到端确认端点和签名校验：

{
  "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "type": "notification.test",
  "created_at": "2026-07-12T10:30:00Z",
  "data": { "message": "TRONAgg notifications are connected." }
}

下一步

• 创建 Webhook——用 API key 注册。
• Webhooks 与通知——配置、通道与 Workspace 流程。
• 查询订单状态——轮询方式，无需 Webhook。