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 changes, 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 in confirmed deposits in total before it can create a webhook. The deposits are cumulative; your current balance may be lower after purchases.

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.
  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. 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}, and POST /webhooks/{id}/test.

What you receive​

Each delivery is a signed JSON POST carrying one event: an envelope (id, type, created_at, data) plus signed headers. Always verify the signature before trusting a delivery, and de-duplicate on the event id — delivery is at-least-once.

The Webhook events reference is the full catalog: the delivery envelope and headers, the signature-verification recipe, every event with an example payload, and which events are on by default. The one most integrations want is order.status_changed — a push alternative to polling GET /order/{id}.

Next steps​