Skip to main content

Webhooks & Notifications

Tracking an order is simple: call GET /order/{id} whenever you want its current status — that's all most integrations need.

Webhooks are optional. If you'd rather not poll, TRONAgg can push you a signed JSON event the moment an order completes or fails, so you update your own record on arrival. Set one up only if you prefer push over polling.

Poll or subscribe — your choice

Polling GET /order/{id} works great and needs no setup. Webhooks are a convenience for when you'd rather be pushed to than poll.

Channels​

Notifications are delivered over one of two channels; the events and preferences are the same for both:

  • Webhook — a signed JSON POST to your backend. For developers and automation.
  • Telegram — readable alerts in a Telegram chat. No code.

Set up a webhook​

Webhooks can be created two ways.

Your account must have more than 1 TRX of net confirmed deposits before it can create a webhook: confirmed deposits minus withdrawals (amount plus fee). Purchases don't reduce this figure; withdrawals do, unless they end rejected, cancelled or failed. A withdrawal from another TRONAgg account to your deposit address doesn't count as a deposit. Until the requirement is met, POST /webhooks returns 400 webhook_deposit_required: its total_deposited_sun field holds this net figure and required_total_deposited_sun is 1000001.

In the Workspace (no code):

  1. Open Workspace → Notifications → Delivery methods → Webhook → Connect.
  2. Give it a name and an HTTPS URL that returns 2xx (see URL requirements).
  3. Copy the signing secret — it is shown once. Store it as a server-side secret; you need it to verify every delivery.
  4. Pick which events go to this webhook in the Notifications tab. Webhooks created in the workspace start with order tracking (order.status_changed) off — switch it on here. Use Send test to fire a sample delivery, and Delivery history to see the last attempts.

With the API — call POST /webhooks with your API key. The signing secret is returned once in the response, so store it right away. A webhook created this way has order tracking (order.status_changed) enabled by default — the event most integrations want — while the rest follow the same per-event defaults you can adjust in the workspace. Manage webhooks with GET /webhooks, DELETE /webhooks/{id} (deletes webhooks only; your Telegram channels are managed in the workspace), and POST /webhooks/{id}/test.

URL requirements​

  • HTTPS only.
  • Public host. The host must resolve only to public IP addresses — not private, loopback, link-local, reserved or multicast ranges. localhost, *.local and tronagg.ai hosts are rejected. This is checked when the webhook is created and again before every delivery and test; a delivery to a host that no longer passes counts as failed.
  • No redirects. Redirects are not followed — a 3xx counts as a failed delivery, so register the final URL.
  • Trailing slash removed. A trailing / is stripped: https://example.com/hook/ is stored and called as https://example.com/hook. Make sure your endpoint answers on the path without the slash.
  • One webhook per URL, and at most 10 webhooks per account.
  • Answer within 10 seconds with a 2xx status.

With the API, a rejected URL, a duplicate URL or an 11th webhook returns 400 validation_error with a message explaining why.

What you receive​

Each delivery is a signed JSON POST carrying one event: an envelope (id, type, created_at, audience, data) plus signed headers. Always verify the signature before trusting a delivery, and de-duplicate on the event id — the same event can arrive more than once. A failed delivery is retried up to 4 more times over about 2.5 hours and then dropped, so reconcile with GET /order/{id} if you must not miss a state.

The Webhook events reference is the full catalog: the delivery envelope and headers, retries, the signature-verification recipe, every event with an example payload, and which events are on by default. New events may be added, so ignore event types you don't recognise. The one most integrations want is order.status_changed — a push alternative to polling GET /order/{id}.

Next steps​