WhitelistHub

Official Python client for the WhitelistHub partner API.

• Pure Python, no third-party dependencies
• Keys, balance, pricing, dynamic VLESS API
• HMAC verification for outbound panel webhooks

Install

pip install whitelisthub

Quickstart

from whitelisthub import PanelClient

client = PanelClient("https://whitelisthub.net", api_token="YOUR_TOKEN")
# [whitelisthub] whitelisthub.net — connected (42 ms) | balance 1500.00 RUB

key = client.keys.create(
    limit_gb=50,
    months=1,
    user_id="tg:1",
    idempotency_key="order-1",
)
print(key.subscription_url)

Disable the startup health check:

client = PanelClient(
    "https://whitelisthub.net",
    api_token="YOUR_TOKEN",
    auto_connect=False,
)

From environment (WHITELISTHUB_API_TOKEN, optional WHITELISTHUB_URL):

client = PanelClient.from_env()

Keys

client.keys.info(key.key_id)
client.keys.renew(key.key_id, months=1)
client.keys.expand(key.key_id, limit_gb=100)
client.keys.reset(key.key_id)
client.keys.ban(key.key_id, message="blocked")
client.keys.unban(key.key_id)
client.keys.delete(key.key_id)

Webhooks

The panel signs outbound events with X-Signature: sha256=<hmac> over the raw request body. Verify with the raw bytes (e.g. Flask request.get_data()), not a re-encoded JSON document.

from flask import Flask, request
from whitelisthub import verify_partner_webhook

app = Flask(__name__)

@app.post("/hooks/panel")
def panel_hook():
    data = verify_partner_webhook(
        request.get_data(),
        signature=request.headers.get("X-Signature"),
        secret="YOUR_WEBHOOK_SECRET",
        max_age_sec=600,
    )
    return {"ok": True, "event": data["event"]}

Docs

• API reference: https://whitelisthub.net/partner/docs
• Packaging: https://packaging.python.org/en/latest/