Webhooks

Overview

Webhooks allow you to receive real-time HTTP notifications when events occur in your Hubsy Cloud account. Instead of polling for changes, Hubsy pushes event data to your specified endpoint.

Setting Up Webhooks

Create Endpoint

Set up an HTTPS endpoint on your server to receive webhook events:

Example Node.js Endpoint

app.post('/webhooks/hubsy', (req, res) => {
  const event = req.body;

  // Verify webhook signature
  if (!verifySignature(req)) {
    return res.status(401).send('Invalid signature');
  }

  // Process event
  handleEvent(event);

  // Respond quickly
  res.status(200).send('OK');
});

curl -X POST https://api.hubsy.cloud/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/hubsy",
    "events": ["file.uploaded", "file.deleted"],
    "secret": "your_webhook_secret"
  }'

Test Webhook

Send a test event to verify setup:

curl -X POST https://api.hubsy.cloud/v1/webhooks/{webhook_id}/test \
  -H "Authorization: Bearer YOUR_API_KEY"

Go Live

Your webhook is now active and will receive events in real-time

Available Events

Subscribe to these events:

file.uploaded

Triggered when a file is uploaded

{
  "event": "file.uploaded",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "file": {
      "id": "file_abc123",
      "name": "document.pdf",
      "size": 2458624,
      "type": "application/pdf",
      "folder_id": "folder_123",
      "uploaded_by": "user_xyz",
      "created_at": "2024-01-15T10:30:00Z"
    }
  }
}

file.deleted

Triggered when a file is deleted

{
  "event": "file.deleted",
  "timestamp": "2024-01-15T11:00:00Z",
  "data": {
    "file": {
      "id": "file_abc123",
      "name": "old-document.pdf",
      "deleted_by": "user_xyz",
      "deleted_at": "2024-01-15T11:00:00Z",
      "permanent": false
    }
  }
}

file.shared

Triggered when a file is shared

{
  "event": "file.shared",
  "timestamp": "2024-01-15T12:00:00Z",
  "data": {
    "file": {
      "id": "file_abc123",
      "name": "presentation.pdf"
    },
    "share": {
      "id": "share_def456",
      "url": "https://hubsy.cloud/s/abc123xyz",
      "password_protected": true,
      "expires_at": "2024-02-15T12:00:00Z",
      "created_by": "user_xyz"
    }
  }
}

Triggered when a shared file is accessed

{
  "event": "share.accessed",
  "timestamp": "2024-01-15T13:00:00Z",
  "data": {
    "share": {
      "id": "share_def456",
      "file_id": "file_abc123"
    },
    "access": {
      "ip_address": "192.168.1.1",
      "user_agent": "Mozilla/5.0...",
      "location": "United States",
      "action": "download"
    }
  }
}

folder.created

Triggered when a folder is created

{
  "event": "folder.created",
  "timestamp": "2024-01-15T14:00:00Z",
  "data": {
    "folder": {
      "id": "folder_789",
      "name": "New Project",
      "parent_id": "folder_123",
      "created_by": "user_xyz"
    }
  }
}

storage.warning

Triggered when storage reaches threshold

{
  "event": "storage.warning",
  "timestamp": "2024-01-15T15:00:00Z",
  "data": {
    "storage": {
      "used": 858993459,
      "limit": 1073741824,
      "percentage": 80,
      "threshold": "80%"
    }
  }
}

user.quota_exceeded

Triggered when storage quota is exceeded

{
  "event": "user.quota_exceeded",
  "timestamp": "2024-01-15T16:00:00Z",
  "data": {
    "storage": {
      "used": 1073741824,
      "limit": 1073741824,
      "overage": 0
    },
    "action_required": true
  }
}

Webhook Payload Structure

All webhook events follow this structure:

{
  "event": "event.name",
  "timestamp": "2024-01-15T10:30:00Z",
  "webhook_id": "webhook_abc123",
  "data": {
    // Event-specific data
  },
  "signature": "sha256=..."
}

string

The event type (e.g., “file.uploaded”)

string

ISO 8601 timestamp when the event occurred

string

ID of the webhook configuration that sent this event

object

Event-specific payload data

string

HMAC SHA-256 signature for verification

Verifying Webhooks

Verify webhook authenticity using the signature:

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = 'sha256=' + hmac.update(JSON.stringify(payload)).digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(digest)
  );
}

app.post('/webhooks/hubsy', (req, res) => {
  const signature = req.headers['x-hubsy-signature'];
  const secret = process.env.WEBHOOK_SECRET;

  if (!verifyWebhook(req.body, signature, secret)) {
    return res.status(401).send('Invalid signature');
  }

  // Process event
  res.status(200).send('OK');
});

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected_sig = 'sha256=' + hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(signature, expected_sig)

@app.route('/webhooks/hubsy', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Hubsy-Signature')
    secret = os.getenv('WEBHOOK_SECRET')
    payload = request.get_data(as_text=True)

    if not verify_webhook(payload, signature, secret):
        return 'Invalid signature', 401

    # Process event
    return 'OK', 200

function verifyWebhook($payload, $signature, $secret) {
    $expectedSig = 'sha256=' . hash_hmac('sha256', $payload, $secret);
    return hash_equals($signature, $expectedSig);
}

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_HUBSY_SIGNATURE'];
$secret = getenv('WEBHOOK_SECRET');

if (!verifyWebhook($payload, $signature, $secret)) {
    http_response_code(401);
    die('Invalid signature');
}

// Process event
http_response_code(200);
echo 'OK';

Managing Webhooks

Create Webhook

curl -X POST https://api.hubsy.cloud/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/hubsy",
    "events": ["file.uploaded", "file.deleted"],
    "secret": "your_webhook_secret",
    "active": true
  }'

List Webhooks

curl https://api.hubsy.cloud/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY"

Update Webhook

curl -X PATCH https://api.hubsy.cloud/v1/webhooks/webhook_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["file.uploaded", "file.deleted", "file.shared"],
    "active": true
  }'

Delete Webhook

curl -X DELETE https://api.hubsy.cloud/v1/webhooks/webhook_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Webhook Delivery

Delivery Behavior

Timeout: 30 seconds
Retries: Up to 3 attempts with exponential backoff
Expected Response: 200-299 status code
Retry Schedule: Immediately, 5 seconds, 25 seconds

Delivery Headers

Hubsy sends these headers with webhook requests:

Content-Type: application/json
X-Hubsy-Signature: sha256=...
X-Hubsy-Event: file.uploaded
X-Hubsy-Webhook-ID: webhook_abc123
X-Hubsy-Delivery-ID: delivery_xyz789
User-Agent: Hubsy-Webhook/1.0

Best Practices

Respond Quickly

Return 200 OK quickly:

Process events asynchronously
Don’t perform long operations in webhook handler
Use a queue for processing
Respond within 5 seconds

Handle Duplicates

Webhooks may be delivered multiple times:

Use delivery ID for idempotency
Track processed events
Handle duplicates gracefully

Secure Your Endpoint

Protect your webhook endpoint:

Always verify signature
Use HTTPS only
Validate payload structure
Rate limit requests

Monitor Failures

Track webhook health:

Monitor delivery success rate
Alert on repeated failures
Review failed deliveries
Update endpoint if needed

Troubleshooting

Not Receiving Webhooks

Check:

Webhook is active
URL is accessible from internet
HTTPS is configured correctly
Firewall allows incoming requests
Server is responding with 200 OK

Signature Verification Fails

Ensure:

Using correct webhook secret
Comparing raw request body
Using timing-safe comparison
Secret hasn’t been rotated

Too Many Events

To reduce volume:

Subscribe only to needed events
Use API polling for some data
Batch process events
Consider using filters (coming soon)

Webhook Logs

View webhook delivery logs in your dashboard:

Delivery attempts and outcomes
Response codes and times
Payload sent
Error messages
Retry history

Or fetch via API:

curl https://api.hubsy.cloud/v1/webhooks/webhook_abc123/deliveries \
  -H "Authorization: Bearer YOUR_API_KEY"

API Documentation

Endpoints

Overview

Setting Up Webhooks

Available Events

Webhook Payload Structure

Verifying Webhooks

Managing Webhooks

Create Webhook

List Webhooks

Update Webhook

Delete Webhook

Webhook Delivery

Delivery Behavior

Delivery Headers

Best Practices

Troubleshooting

Webhook Logs

​Overview

​Setting Up Webhooks

​Available Events

​Webhook Payload Structure

​Verifying Webhooks

​Managing Webhooks

​Create Webhook

​List Webhooks

​Update Webhook

​Delete Webhook

​Webhook Delivery

​Delivery Behavior

​Delivery Headers

​Best Practices

​Troubleshooting

​Webhook Logs

Overview

Setting Up Webhooks

Available Events

Webhook Payload Structure

Verifying Webhooks

Managing Webhooks

Create Webhook

List Webhooks

Update Webhook

Delete Webhook

Webhook Delivery

Delivery Behavior

Delivery Headers

Best Practices

Troubleshooting

Webhook Logs