Webhooks

Overview

Webhooks let you receive HTTP POST callbacks whenever specific events occur in V2RayTun. Use them to integrate with external systems — billing platforms, monitoring tools, chat bots, or custom automation.

Configuration

1. Navigate to Settings → Webhooks in the panel.
2. Click Add Webhook.
3. Enter the URL that will receive the POST requests.
4. Select the events you want to subscribe to.
5. Optionally set a secret for payload signature verification.
6. Save.

Event Types

Payload Format

Every webhook request is a JSON POST with the following structure:

{
  "event": "user.created",
  "timestamp": "2025-06-10T14:30:00Z",
  "data": {
    "id": 42,
    "username": "alice",
    "squadId": 1,
    "trafficLimitGB": 50,
    "expiresAt": "2025-12-31T23:59:59Z"
  }
}

Headers

Signature Verification

If you configured a secret, verify the payload integrity:

import hmac
import hashlib
 
def verify_signature(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

Retry Policy

V2RayTun retries failed deliveries (non-2xx responses) up to 3 times with exponential backoff:

After three failures the delivery is marked as failed. You can view delivery logs in Settings → Webhooks → Delivery History.

Testing

Use the Test button next to any configured webhook to send a sample ping event and verify your endpoint is reachable.