Webhook Integration

Overview

OrbVPN provides a webhook system that allows you to receive real-time notifications about various events in your application. You can configure webhooks to send data to Slack, GoHighLevel, or Zapier.

Supported Providers

• Slack: For team notifications and monitoring
• GoHighLevel: For CRM integration and customer management
• Zapier: For custom workflow automation

Event Types

User-Related Events

• USER_CREATED: When a new user is registered
• USER_DELETED: When a user account is deleted
• USER_ACTION: Generic user activities
• USER_LOGIN: When a user logs in
• USER_LOGOUT: When a user logs out
• USER_PASSWORD_CHANGED: When a user changes their password
• USER_EMAIL_VERIFIED: When a user verifies their email
• USER_PROFILE_UPDATED: When user profile information is updated

Subscription Events

• SUBSCRIPTION_CREATED: When a new subscription is created
• SUBSCRIPTION_RENEWED: When a subscription is renewed
• SUBSCRIPTION_CANCELLED: When a subscription is cancelled
• SUBSCRIPTION_EXPIRED: When a subscription expires
• SUBSCRIPTION_TRIAL_STARTED: When a trial period begins
• SUBSCRIPTION_TRIAL_ENDED: When a trial period ends
• SUBSCRIPTION_UPGRADED: When a subscription is upgraded
• SUBSCRIPTION_DOWNGRADED: When a subscription is downgraded

Payment Events

• PAYMENT_RECEIVED: When a payment is successfully processed
• PAYMENT_FAILED: When a payment attempt fails
• PAYMENT_REFUNDED: When a payment is refunded
• PAYMENT_PENDING: When a payment is awaiting processing

Device Events

• DEVICE_CONNECTED: When a device connects to VPN
• DEVICE_DISCONNECTED: When a device disconnects from VPN
• DEVICE_ADDED: When a new device is registered
• DEVICE_REMOVED: When a device is removed
• DEVICE_LIMIT_REACHED: When user reaches their device limit

Security Events

• SECURITY_LOGIN_ATTEMPT: Failed login attempts
• SECURITY_PASSWORD_RESET: Password reset requests
• SECURITY_2FA_ENABLED: When 2FA is enabled
• SECURITY_2FA_DISABLED: When 2FA is disabled
• SECURITY_IP_BLOCKED: When an IP address is blocked

Reseller Events

• RESELLER_CREATED: When a new reseller account is created
• RESELLER_UPDATED: When reseller information is updated
• RESELLER_DELETED: When a reseller account is removed
• RESELLER_CREDIT_ADDED: When credit is added to reseller account
• RESELLER_CREDIT_DEDUCTED: When credit is deducted from reseller account

System Events

• SYSTEM_MAINTENANCE_START: When system maintenance begins
• SYSTEM_MAINTENANCE_END: When system maintenance ends
• SYSTEM_SERVER_DOWN: When a server becomes unavailable
• SYSTEM_SERVER_UP: When a server becomes available
• SYSTEM_UPDATE: When system updates are applied

Usage Events

• USAGE_LIMIT_APPROACHING: When user approaches bandwidth limit
• USAGE_LIMIT_REACHED: When user reaches bandwidth limit
• USAGE_ABNORMAL: When unusual usage patterns are detected

Example Webhook Configuration with Multiple Events

{
  "name": "All User Events Monitor",
  "providerType": "SLACK",
  "endpoint": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
  "active": true,
  "subscribedEvents": [
    "USER_CREATED",
    "USER_DELETED",
    "USER_ACTION",
    "USER_LOGIN",
    "USER_LOGOUT",
    "SUBSCRIPTION_CREATED",
    "SUBSCRIPTION_EXPIRED",
    "PAYMENT_RECEIVED",
    "PAYMENT_FAILED"
  ],
  "providerSpecificConfig": {
    "channel": "#user-events",
    "username": "OrbVPN Monitor",
    "icon_emoji": ":shield:"
  },
  "maxRetries": 3,
  "retryDelay": 60
}

## Webhook Configuration

### Configuration Object

```json
{
  "name": "My Webhook",
  "providerType": "SLACK",
  "endpoint": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
  "active": true,
  "subscribedEvents": ["USER_CREATED", "USER_DELETED"],
  "providerSpecificConfig": {
    "channel": "#notifications",
    "username": "OrbVPN Bot",
    "icon_emoji": ":robot_face:"
  },
  "maxRetries": 3,
  "retryDelay": 60
}

Provider-Specific Configurations

Slack Configuration

{
  "channel": "#notifications",
  "username": "OrbVPN Bot",
  "icon_emoji": ":robot_face:",
  "icon_url": "https://your-icon-url.com/icon.png"
}

GoHighLevel Configuration

{
  "locationId": "your-location-id",
  "apiKey": "your-api-key",
  "source": "OrbVPN"
}

Zapier Configuration

{
  "api_key": "your-zapier-key",
  "source": "OrbVPN",
  "version": "1.0"
}

Payload Formats

User Created Event

{
  "eventType": "USER_CREATED",
  "timestamp": "2024-11-03T15:27:47.002948",
  "userId": 63396,
  "email": "user@example.com",
  "username": "user@example.com",
  "profile": {
    "firstName": "John",
    "lastName": "Doe",
    "country": "US",
    "phone": "+1234567890"
  },
  "subscription": {
    "groupName": "3 Month",
    "groupId": 3,
    "multiLoginCount": 5,
    "expiresAt": "2025-02-01T15:27:22.887568",
    "isTrialPeriod": false
  },
  "reseller": {
    "id": 1,
    "level": "OWNER",
    "discountPercent": 100.0,
    "levelId": 6,
    "credit": 600.0
  },
  "active": true,
  "autoRenew": false
}

Provider-Specific Data Formats

Slack Format

Messages in Slack are formatted with sections for better readability:

• Event Header with timestamp
• User Information
• Profile Details (if available)
• Subscription Details
• Reseller Information

Example Slack message:

🔔 *USER_CREATED*
Time: Nov 03, 2024 15:27:47

👤 *User Information*
-------------------
• Email: user@example.com
• Username: user@example.com
• User ID: 63396

📋 *Profile Details*
-------------------
• Name: John Doe
• Country: US
• Phone: +1234567890

📅 *Subscription Details*
-------------------
• Plan: 3 Month
• Multi-Login Count: 5
• Expires At: Feb 01, 2025 15:27:22
• Auto Renew: false

GoHighLevel Format

Data is flattened for easy mapping in GoHighLevel:

{
  "contact": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "user@example.com",
    "phone": "+1234567890",
    "address1": "",
    "city": "",
    "country": "US",
    "postalCode": ""
  },
  "customFields": {
    "user_id": "63396",
    "subscription_group": "3 Month",
    "subscription_status": "ACTIVE",
    "subscription_expiresAt": "2025-02-01T15:27:22.887568"
  },
  "tags": ["OrbVPN User", "New User"],
  "locationId": "your-location-id"
}

Zapier Format

Data is structured with snake_case for Zapier conventions:

{
  "event_type": "USER_CREATED",
  "occurred_at": "2024-11-03T15:27:47.002948",
  "user_id": 63396,
  "email": "user@example.com",
  "username": "user@example.com",
  "profile": {
    "first_name": "John",
    "last_name": "Doe",
    "country": "US",
    "phone": "+1234567890"
  },
  "subscription": {
    "group_name": "3 Month",
    "duration_days": "90",
    "multi_login_count": 5,
    "expires_at": "2025-02-01T15:27:22.887568"
  }
}

Retry Mechanism

• Maximum retries: 3 (configurable)
• Retry delays: 30s, 120s, 300s (configurable)
• Signature verification available for security

Error Handling

Webhooks include proper error handling:

• Delivery status tracking
• Error message logging
• Retry count tracking
• Response data storage

Testing

You can test your webhook configuration using the test endpoint:

mutation {
  testWebhookConfiguration(id: "your-webhook-id")
}

Best Practices

1. Always validate your endpoint URL
2. Set appropriate retry policies
3. Monitor webhook deliveries
4. Handle duplicate events
5. Use proper error handling
6. Secure your webhook endpoints

Rate Limits

• Default: 10 requests per second
• Customizable based on your needs
• Automatic retry for rate limit errors