Webhooks Overview

Receive real-time notifications for account events

Webhooks

Configure a webhook URL to receive real-time HTTP POST notifications when events occur on your account.

Supported events

Event	Description
order.filled	Energy order completed
order.failed	Energy order failed
deposit.confirmed	Deposit credited to balance
invoice.paid	Invoice payment received
invoice.delegated	Invoice energy delegated
smart_mode.transfer	Smart Mode transfer processed
withdrawal.completed	Withdrawal sent

Webhook payload

{
  "event": "order.filled",
  "data": {
    "order_id": 1234,
    "address": "TAddress...",
    "energy_amount": 65000,
    "price_trx": "2.75"
  },
  "timestamp": "2026-03-04T12:00:00Z"
}

Requirements

• URL must use HTTPS
• Must respond with 2xx status within 10 seconds
• Failed deliveries are retried up to 3 times with exponential backoff

Verifying webhook signatures

Every webhook request includes an X-Webhook-Signature header containing an HMAC-SHA256 signature. Use this to verify that the request is from TronRental.

The signature is computed over the raw request body using your webhook secret (returned when you configure your webhook).

Python

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

# In your webhook handler:
# payload = request.body  (raw bytes)
# signature = request.headers["X-Webhook-Signature"]
# secret = "whsec_abc123..."  (from configure response)
# if not verify_webhook(payload, signature, secret):
#     return Response(status_code=401)

Always verify the signature before processing webhook data. Use constant-time comparison (hmac.compare_digest / crypto.timingSafeEqual) to prevent timing attacks.

Webhook URLs cannot point to localhost, 127.0.0.1, or other private addresses.