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).
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.
