Webhooks
Configura una URL de webhook para recibir notificaciones HTTP POST en tiempo real cuando ocurran eventos en tu cuenta.
Eventos soportados
| Evento | Descripcion |
|---|
order.filled | Orden de energia completada |
order.failed | Orden de energia fallida |
deposit.confirmed | Deposito acreditado al saldo |
invoice.paid | Pago de factura recibido |
invoice.delegated | Energia de factura delegada |
smart_mode.transfer | Transferencia de Smart Mode procesada |
withdrawal.completed | Retiro enviado |
Carga del webhook
{
"event": "order.filled",
"data": {
"order_id": 1234,
"address": "TAddress...",
"energy_amount": 65000,
"price_trx": "2.75"
},
"timestamp": "2026-03-04T12:00:00Z"
}
Requisitos
- La URL debe usar HTTPS
- Debe responder con estado
2xx en 10 segundos
- Las entregas fallidas se reintentan hasta 3 veces con retroceso exponencial
Verificacion de firmas de webhook
Cada solicitud de webhook incluye un encabezado X-Webhook-Signature que contiene una firma HMAC-SHA256. Utiliza esto para verificar que la solicitud proviene de TronRental.
La firma se calcula sobre el cuerpo crudo de la solicitud usando tu secreto de webhook (devuelto cuando configuras tu 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)
Siempre verifica la firma antes de procesar los datos del webhook. Usa comparacion de tiempo constante (hmac.compare_digest / crypto.timingSafeEqual) para prevenir ataques de temporizado.
Las URLs de webhook no pueden apuntar a localhost, 127.0.0.1 u otras direcciones privadas.
