Webhook 与通知
跟踪订单很简单：随时调用 GET /order/{id} 即可获取它的当前状态——大多数集成只需要这些。
Webhook 是可选的。 如果你不想轮询，TRONAgg 可以在订单完成或失败的那一刻向你推送一条带签名的 JSON 事件，你在收到时更新自己的记录即可。只有在你更偏好推送而非轮询时，才需要配置它。
轮询 GET /order/{id} 效果很好，且无需任何配置。Webhook 只是一种便利，适合你更希望被推送而不是主动轮询的场景。
渠道
通知通过以下两种渠道之一送达；两者的事件与偏好设置完全相同：
- Webhook——向你的后端发送带签名的 JSON
POST。面向开发者与自动化。 - Telegram——在 Telegram 聊天中收到易读的提醒。无需代码。
配置 Webhook
Webhook 有两种创建方式。
账户的净确认充值必须超过 1 TRX，才能创建 Webhook：已确认的充值减去提现（金额加手续费）。购买不会减少该数值；提现会减少它，除非提现最终被拒绝、取消或失败。从另一个 TRONAgg 账户提现到你的充值地址不算作充值。在满足要求之前，POST /webhooks 返回 400 webhook_deposit_required：其 total_deposited_sun 字段是这一净值，required_total_deposited_sun 为 1000001。
在工作台中（无需代码）：
- 打开 工作台 → 通知 → 发送方式 → Webhook → 连接。
- 填写名称和一个返回
2xx的 HTTPS URL（见 URL 要求）。 - 复制签名密钥——它只显示一次。请将其作为服务端机密保存；验证每一次投递都需要它。
- 在 通知 标签页中选择哪些事件发往该 Webhook。在工作台中创建的 Webhook，订单跟踪（
order.status_changed）初始为关闭——请在这里开启。用 发送测试 发出一条示例投递，用 最近发送记录 查看最近的投递尝试。
通过 API——用你的 API 密钥调用 POST /webhooks。签名密钥只在响应中返回一次，请立即保存。以这种方式创建的 Webhook 默认启用订单跟踪（order.status_changed）——大多数集成需要的事件——其余事件沿用相同的按事件默认值，你可以在工作台中调整。用 GET /webhooks、DELETE /webhooks/{id}（只删除 Webhook；你的 Telegram 渠道在工作台中管理）和 POST /webhooks/{id}/test 管理 Webhook。
URL 要求
- 仅限 HTTPS。
- 公网主机。 主机只能解析到公网 IP 地址——不能是私有、回环、链路本地、保留或组播地址段。
localhost、*.local和tronagg.ai主机会被拒绝。创建 Webhook 时会检查，每次投递和测试前也会再次检查；投递到不再满足要求的主机会被计为失败。 - 不跟随重定向。 重定向不会被跟随——
3xx计为投递失败，因此请注册最终 URL。 - 去除末尾斜杠。 末尾的
/会被去掉：https://example.com/hook/将以https://example.com/hook保存和调用。请确保你的端点在不带斜杠的路径上响应。 - 每个 URL 只能注册一个 Webhook，每个账户最多 10 个 Webhook。
- 在 10 秒内响应，并返回
2xx状态码。
通过 API 时，被拒绝的 URL、重复的 URL 或第 11 个 Webhook 会返回 400 validation_error，并在 message 中说明原因。
你会收到什么
每次投递都是一个带签名的 JSON POST，携带一个事件：一个信封（id、type、created_at、audience、data）加上带签名的请求头。在信任任何投递之前，务必先验证签名，并按事件 id 去重——同一事件可能到达不止一次。失败的投递会在大约 2.5 小时内最多再重试 4 次，之后被丢弃；因此如果你不能错过任何状态，请用 GET /order/{id} 对账。
Webhook 事件 参考页是完整目录：投递信封与请求头、重试、签名验证方法、每个事件及其示例负载，以及哪些事件默认开启。未来可能新增事件，因此请忽略你不认识的事件类型。大多数集成需要的是 order.status_changed——轮询 GET /order/{id} 之外的推送方案。
下一步
- Webhook 事件——完整的事件目录、投递信封与签名验证。
- 跟踪订单状态——轮询端点，仍可用于按需查询。
- 代码示例——完整的购买 → 跟踪流程。