Webhooks & Advanced Features

Learn about real-time notifications and advanced API capabilities.

What are Webhooks?

Webhooks allow your application to receive real-time notifications when events occur in QbitSpark. Instead of polling our API, we'll send HTTP POST requests to your specified endpoints.

Supported Events

Event Type	Description	Trigger
`user.created`	New user registered	User signs up
`user.updated`	User info changed	Profile update
`user.deleted`	User removed	Account deletion
`project.created`	New project added	Project creation
`project.deployed`	Project went live	Deployment complete
`payment.success`	Payment processed	Subscription paid
`payment.failed`	Payment declined	Payment issue

Setting Up Webhooks

1. Configure Webhook URL

POST /webhooks
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "url": "https://your-app.com/webhooks/qbitspark",
  "events": ["user.created", "project.deployed"],
  "secret": "your-webhook-secret-key",
  "active": true
}

2. Webhook Payload Structure

{
  "event": "user.created",
  "timestamp": "2024-09-22T10:30:00Z",
  "webhook_id": "wh_abc123",
  "data": {
    "user": {
      "id": 456,
      "email": "newuser@example.com",
      "name": "New User",
      "created_at": "2024-09-22T10:30:00Z"
    }
  }
}

3. Verify Webhook Signature

Always verify webhook authenticity:

import hmac
import hashlib

def verify_webhook_signature(payload, signature, secret):
    """Verify webhook signature for security"""
    expected_signature = hmac.new(
        secret.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(signature, f"sha256={expected_signature}")

# Usage
is_valid = verify_webhook_signature(
    payload_body,
    request.headers['X-QbitSpark-Signature'],
    'your-webhook-secret-key'
)

Advanced Filtering

GraphQL-style Queries

For complex data retrieval, use our GraphQL endpoint:

query GetProjectsWithUsers {
  projects(status: ACTIVE, limit: 10) {
    id
    name
    created_at
    owner {
      id
      name
      email
    }
    collaborators {
      id
      name
      role
    }
  }
}

Request Example

POST /graphql
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "query": "query GetProjectsWithUsers { projects(status: ACTIVE) { id name owner { name email } } }"
}

Real-time Subscriptions

WebSocket Connection

Connect to our WebSocket for real-time updates:

const ws = new WebSocket('wss://api.qbitspark.com/realtime');

ws.onopen = function() {
  // Authenticate
  ws.send(JSON.stringify({
    type: 'auth',
    token: 'YOUR_API_KEY'
  }));
  
  // Subscribe to events
  ws.send(JSON.stringify({
    type: 'subscribe',
    channels: ['projects', 'users']
  }));
};

ws.onmessage = function(event) {
  const data = JSON.parse(event.data);
  console.log('Real-time update:', data);
};

Batch Operations

Bulk User Creation

Create multiple users in a single request:

POST /users/batch
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "users": [
    {
      "email": "user1@example.com",
      "name": "User One",
      "role": "developer"
    },
    {
      "email": "user2@example.com", 
      "name": "User Two",
      "role": "viewer"
    }
  ],
  "send_invites": true
}

Bulk Response

{
  "success": true,
  "results": [
    {
      "success": true,
      "user_id": 789,
      "email": "user1@example.com"
    },
    {
      "success": false,
      "error": "Email already exists",
      "email": "user2@example.com"
    }
  ],
  "summary": {
    "total": 2,
    "created": 1,
    "failed": 1
  }
}

SDK Libraries

Official SDKs

We provide official SDKs for popular languages:

# Node.js
npm install @qbitspark/api-client

# Python
pip install qbitspark-sdk

# PHP
composer require qbitspark/php-sdk

# Go
go get github.com/qbitspark/go-sdk

Quick SDK Usage

// Node.js SDK
const QbitSpark = require('@qbitspark/api-client');

const client = new QbitSpark({
  apiKey: 'YOUR_API_KEY',
  environment: 'production' // or 'sandbox'
});

// Get users with automatic pagination
const allUsers = await client.users.list({ 
  status: 'active',
  autoPage: true 
});

console.log(`Found ${allUsers.length} active users`);

Monitoring & Analytics

API Usage Dashboard

Track your API usage at: https://dashboard.qbitspark.com/api

Usage Metrics Available:

✅ Request volume by endpoint
✅ Response times and performance
✅ Error rates and failure analysis
✅ Rate limit consumption
✅ Geographic request distribution

Support & Resources

📧 Technical Support: api-support@qbitspark.com
📖 API Status: https://status.qbitspark.com
💬 Discord Community: https://discord.gg/qbitspark
🐛 Bug Reports: https://github.com/qbitspark/issues

Need Help? Our developer success team is here to help you integrate successfully. Contact us at office@qbitspark.com