Integration Guides

Understanding Webhooks

Webhooks are HTTP callbacks that WorkSkedge sends to your server when specific events occur. Instead of constantly polling our API for changes, webhooks push updates to you instantly.

Step 1: Create a Webhook Endpoint

First, you need to create an endpoint on your server that can receive webhook events from WorkSkedge.

const express = require('express');
const crypto = require('crypto');
const app = express();

app.use(express.json());

// Webhook secret from WorkSkedge settings
const WEBHOOK_SECRET = process.env.WORKSKEDGE_WEBHOOK_SECRET;

// Verify webhook signature
function verifySignature(payload, signature) {
  const hmac = crypto.createHmac('sha256', WEBHOOK_SECRET);
  const digest = hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(digest)
  );
}

app.post('/webhooks/workskedge', (req, res) => {
  const signature = req.headers['x-workskedge-signature'];
  const payload = JSON.stringify(req.body);

  // Verify the request came from WorkSkedge
  if (!verifySignature(payload, signature)) {
    console.error('Invalid webhook signature');
    return res.status(401).send('Invalid signature');
  }

  const event = req.body;
  console.log('Received webhook event:', event.event_type);

  // Handle different event types
  switch (event.event_type) {
    case 'work_order.created':
      handleWorkOrderCreated(event.data);
      break;
    case 'work_order.updated':
      handleWorkOrderUpdated(event.data);
      break;
    case 'project.created':
      handleProjectCreated(event.data);
      break;
    default:
      console.log('Unhandled event type:', event.event_type);
  }

  // Respond quickly to acknowledge receipt
  res.status(200).json({ received: true });
});

function handleWorkOrderCreated(data) {
  console.log('New work order created:', data.id);
  // Your business logic here
}

function handleWorkOrderUpdated(data) {
  console.log('Work order updated:', data.id);
  // Your business logic here
}

function handleProjectCreated(data) {
  console.log('New project created:', data.id);
  // Your business logic here
}

app.listen(3000, () => {
  console.log('Webhook server listening on port 3000');
});

from flask import Flask, request, jsonify
import hmac
import hashlib
import os

app = Flask(__name__)

WEBHOOK_SECRET = os.environ.get('WORKSKEDGE_WEBHOOK_SECRET')

def verify_signature(payload, signature):
    """Verify webhook signature"""
    mac = hmac.new(
        WEBHOOK_SECRET.encode(),
        msg=payload.encode(),
        digestmod=hashlib.sha256
    )
    return hmac.compare_digest(mac.hexdigest(), signature)

@app.route('/webhooks/workskedge', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('X-Workskedge-Signature')
    payload = request.get_data(as_text=True)

    # Verify the request came from WorkSkedge
    if not verify_signature(payload, signature):
        print('Invalid webhook signature')
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.json
    print(f"Received webhook event: {event['event_type']}")

    # Handle different event types
    event_type = event['event_type']
    if event_type == 'work_order.created':
        handle_work_order_created(event['data'])
    elif event_type == 'work_order.updated':
        handle_work_order_updated(event['data'])
    elif event_type == 'project.created':
        handle_project_created(event['data'])
    else:
        print(f"Unhandled event type: {event_type}")

    # Respond quickly to acknowledge receipt
    return jsonify({'received': True}), 200

def handle_work_order_created(data):
    print(f"New work order created: {data['id']}")
    # Your business logic here

def handle_work_order_updated(data):
    print(f"Work order updated: {data['id']}")
    # Your business logic here

def handle_project_created(data):
    print(f"New project created: {data['id']}")
    # Your business logic here

if __name__ == '__main__':
    app.run(port=3000)

<?php
$webhookSecret = $_ENV['WORKSKEDGE_WEBHOOK_SECRET'];

// Get webhook payload
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WORKSKEDGE_SIGNATURE'] ?? '';

// Verify webhook signature
function verifySignature($payload, $signature, $secret) {
    $computedSignature = hash_hmac('sha256', $payload, $secret);
    return hash_equals($computedSignature, $signature);
}

if (!verifySignature($payload, $signature, $webhookSecret)) {
    http_response_code(401);
    echo json_encode(['error' => 'Invalid signature']);
    exit;
}

$event = json_decode($payload, true);
error_log('Received webhook event: ' . $event['event_type']);

// Handle different event types
switch ($event['event_type']) {
    case 'work_order.created':
        handleWorkOrderCreated($event['data']);
        break;
    case 'work_order.updated':
        handleWorkOrderUpdated($event['data']);
        break;
    case 'project.created':
        handleProjectCreated($event['data']);
        break;
    default:
        error_log('Unhandled event type: ' . $event['event_type']);
}

// Respond quickly to acknowledge receipt
http_response_code(200);
echo json_encode(['received' => true]);

function handleWorkOrderCreated($data) {
    error_log('New work order created: ' . $data['id']);
    // Your business logic here
}

function handleWorkOrderUpdated($data) {
    error_log('Work order updated: ' . $data['id']);
    // Your business logic here
}

function handleProjectCreated($data) {
    error_log('New project created: ' . $data['id']);
    // Your business logic here
}
?>

Step 2: Configure Your Webhook in WorkSkedge

Once your endpoint is ready and accessible from the internet, configure it in WorkSkedge.

Step 3: Handle Webhook Events

Each webhook event has a consistent structure with an event type and data payload.

{
  "event_id": "evt_1234567890abcdef",
  "event_type": "work_order.created",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "id": "wo_abc123xyz789",
    "title": "Install HVAC System",
    "description": "Install new HVAC system in building A",
    "status": "scheduled",
    "priority": "high",
    "project_id": "proj_1234567890",
    "assigned_to": ["emp_abc123", "emp_xyz789"],
    "scheduled_start": "2025-01-20T08:00:00Z",
    "scheduled_end": "2025-01-20T17:00:00Z",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  }
}

Best Practices

app.post('/webhooks/workskedge', async (req, res) => {
  // Respond immediately
  res.status(200).json({ received: true });

  // Process asynchronously
  await queue.add('webhook-processing', {
    event: req.body
  });
});

const processedEvents = new Set();

function handleWebhookEvent(event) {
  // Check if we've already processed this event
  if (processedEvents.has(event.event_id)) {
    console.log('Duplicate event, skipping:', event.event_id);
    return;
  }

  // Process the event
  processEvent(event);

  // Mark as processed
  processedEvents.add(event.event_id);
}

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const computedSignature = hmac.update(payload).digest('hex');

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

app.post('/webhooks/workskedge', async (req, res) => {
  try {
    // Verify signature
    if (!verifySignature(req.body, req.headers['x-workskedge-signature'])) {
      return res.status(401).send('Invalid signature');
    }

    // Respond immediately
    res.status(200).json({ received: true });

    // Process event with error handling
    try {
      await processWebhookEvent(req.body);
    } catch (error) {
      console.error('Error processing webhook:', error);
      // Log to error tracking service
      errorTracker.captureException(error, {
        extra: { event: req.body }
      });
    }
  } catch (error) {
    console.error('Critical webhook error:', error);
    res.status(500).send('Internal server error');
  }
});

Testing Webhooks Locally

During development, you need to expose your local server to the internet for WorkSkedge to reach it. We recommend using ngrok.

# Download from https://ngrok.com or use package manager
brew install ngrok  # macOS
# or
npm install -g ngrok  # npm

node server.js  # Start your webhook endpoint on port 3000

ngrok http 3000

Common Webhook Patterns

Pattern 1: Sync to External System

When a work order is created in WorkSkedge, automatically create a corresponding ticket in your help desk system.

async function handleWorkOrderCreated(workOrder) {
  try {
    // Create ticket in external system
    const ticket = await helpDeskAPI.createTicket({
      title: workOrder.title,
      description: workOrder.description,
      priority: workOrder.priority,
      external_id: workOrder.id
    });

    console.log(`Created help desk ticket ${ticket.id} for work order ${workOrder.id}`);
  } catch (error) {
    console.error('Failed to sync work order:', error);
  }
}

Pattern 2: Send Notifications

Notify team members via email or Slack when they're assigned to a work order.

async function handleWorkOrderCreated(workOrder) {
  // Fetch employee details
  const employees = await Promise.all(
    workOrder.assigned_to.map(id => getEmployee(id))
  );

  // Send notifications
  for (const employee of employees) {
    await sendEmail({
      to: employee.email,
      subject: `New Assignment: ${workOrder.title}`,
      body: `You've been assigned to: ${workOrder.title}\n\n` +
            `Scheduled: ${workOrder.scheduled_start}\n` +
            `Priority: ${workOrder.priority}`
    });

    await sendSlackMessage({
      channel: employee.slack_id,
      text: `🔨 New work order assigned: ${workOrder.title}`
    });
  }
}

Pattern 3: Update Analytics

Track work order metrics in your analytics dashboard.

async function handleWorkOrderStatusChanged(workOrder) {
  await analytics.track({
    event: 'work_order_status_changed',
    properties: {
      work_order_id: workOrder.id,
      old_status: workOrder.previous_status,
      new_status: workOrder.status,
      project_id: workOrder.project_id,
      duration_hours: calculateDuration(workOrder)
    }
  });

  // Update real-time dashboard
  await dashboard.updateMetric('active_work_orders', {
    increment: workOrder.status === 'in_progress' ? 1 : 0,
    decrement: workOrder.status === 'completed' ? 1 : 0
  });
}

Next Steps

Pattern 1: Pagination - Fetching All Resources

When fetching large datasets, use pagination to retrieve all records efficiently without hitting memory limits.

const API_KEY = process.env.WORKSKEDGE_API_KEY;
const BASE_URL = 'https://app.workskedge.com/api/v1';

async function fetchAllProjects() {
  const allProjects = [];
  let offset = 0;
  const limit = 100; // Max allowed per request
  let hasMore = true;

  while (hasMore) {
    const response = await fetch(
      `${BASE_URL}/projects?limit=${limit}&offset=${offset}`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        }
      }
    );

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const result = await response.json();

    allProjects.push(...result.data);
    hasMore = result.pagination.has_more;
    offset += limit;

    console.log(`Fetched ${allProjects.length} of ${result.pagination.total} projects`);
  }

  return allProjects;
}

// Usage
const allProjects = await fetchAllProjects();
console.log(`Total projects fetched: ${allProjects.length}`);

Pattern 2: Bulk Operations with Batch Processing

When creating or updating multiple resources, process them in batches to optimize performance and handle rate limits.

async function batchCreateEmployees(employees) {
  const BATCH_SIZE = 10;
  const DELAY_MS = 1000; // Wait 1 second between batches
  const results = [];
  const errors = [];

  for (let i = 0; i < employees.length; i += BATCH_SIZE) {
    const batch = employees.slice(i, i + BATCH_SIZE);

    console.log(`Processing batch ${Math.floor(i / BATCH_SIZE) + 1} of ${Math.ceil(employees.length / BATCH_SIZE)}`);

    const batchPromises = batch.map(async (employee) => {
      try {
        const response = await fetch(`${BASE_URL}/employees`, {
          method: 'POST',
          headers: {
            'Authorization': `Bearer ${API_KEY}`,
            'Content-Type': 'application/json'
          },
          body: JSON.stringify(employee)
        });

        if (!response.ok) {
          const error = await response.json();
          throw new Error(error.message);
        }

        const result = await response.json();
        return { success: true, data: result };
      } catch (error) {
        return {
          success: false,
          employee: employee,
          error: error.message
        };
      }
    });

    const batchResults = await Promise.all(batchPromises);

    batchResults.forEach(result => {
      if (result.success) {
        results.push(result.data);
      } else {
        errors.push(result);
      }
    });

    // Wait before processing next batch (rate limiting)
    if (i + BATCH_SIZE < employees.length) {
      await new Promise(resolve => setTimeout(resolve, DELAY_MS));
    }
  }

  return {
    successful: results.length,
    failed: errors.length,
    results,
    errors
  };
}

// Usage
const employeesToCreate = [
  { first_name: 'John', last_name: 'Doe', email: 'john@example.com', role: 'technician' },
  { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com', role: 'supervisor' },
  // ... more employees
];

const result = await batchCreateEmployees(employeesToCreate);
console.log(`Created ${result.successful} employees, ${result.failed} failed`);

Pattern 3: Optimistic Updates with Error Recovery

Update your UI immediately for better user experience, then sync with the API and handle any conflicts.

class WorkOrderManager {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.pendingUpdates = new Map();
  }

  async updateWorkOrder(workOrderId, updates) {
    // Store original state for rollback
    const originalState = await this.getWorkOrder(workOrderId);

    // Apply optimistic update to local state/UI
    this.applyOptimisticUpdate(workOrderId, updates);

    try {
      // Send update to API
      const response = await fetch(
        `${BASE_URL}/work-orders/${workOrderId}`,
        {
          method: 'PUT',
          headers: {
            'Authorization': `Bearer ${this.apiKey}`,
            'Content-Type': 'application/json'
          },
          body: JSON.stringify(updates)
        }
      );

      if (!response.ok) {
        throw new Error(`Failed to update: ${response.status}`);
      }

      const updatedWorkOrder = await response.json();

      // Confirm the update
      this.confirmUpdate(workOrderId, updatedWorkOrder);
      return updatedWorkOrder;

    } catch (error) {
      console.error('Update failed, rolling back:', error);

      // Rollback to original state
      this.rollbackUpdate(workOrderId, originalState);

      // Show error to user
      this.showError(`Failed to update work order: ${error.message}`);

      throw error;
    }
  }

  applyOptimisticUpdate(id, updates) {
    // Update local state immediately
    console.log(`Optimistically updating work order ${id}`);
    this.pendingUpdates.set(id, updates);
    // Update UI here
  }

  confirmUpdate(id, serverState) {
    console.log(`Confirmed update for work order ${id}`);
    this.pendingUpdates.delete(id);
    // Update UI with server state
  }

  rollbackUpdate(id, originalState) {
    console.log(`Rolling back work order ${id} to original state`);
    this.pendingUpdates.delete(id);
    // Restore original state in UI
  }

  async getWorkOrder(id) {
    const response = await fetch(`${BASE_URL}/work-orders/${id}`, {
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      }
    });
    return await response.json();
  }

  showError(message) {
    // Display error to user
    console.error(message);
  }
}

// Usage
const manager = new WorkOrderManager(API_KEY);

try {
  await manager.updateWorkOrder('wo_123', {
    status: 'in_progress'
  });
} catch (error) {
  // Error already handled by manager
}

Pattern 4: Caching with Smart Invalidation

Implement caching to reduce API calls, but invalidate the cache intelligently when data changes.

class CachedAPIClient {
  constructor(apiKey, cacheDuration = 300000) { // 5 minutes default
    this.apiKey = apiKey;
    this.cacheDuration = cacheDuration;
    this.cache = new Map();
  }

  getCacheKey(endpoint, params = {}) {
    return `${endpoint}?${new URLSearchParams(params).toString()}`;
  }

  isCacheValid(cacheEntry) {
    if (!cacheEntry) return false;
    return Date.now() - cacheEntry.timestamp < this.cacheDuration;
  }

  async get(endpoint, params = {}) {
    const cacheKey = this.getCacheKey(endpoint, params);
    const cached = this.cache.get(cacheKey);

    // Return cached data if valid
    if (this.isCacheValid(cached)) {
      console.log(`Cache hit for ${cacheKey}`);
      return cached.data;
    }

    // Fetch fresh data
    console.log(`Cache miss for ${cacheKey}, fetching...`);
    const queryString = new URLSearchParams(params).toString();
    const url = `${BASE_URL}${endpoint}${queryString ? '?' + queryString : ''}`;

    const response = await fetch(url, {
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      }
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();

    // Cache the response
    this.cache.set(cacheKey, {
      data,
      timestamp: Date.now()
    });

    return data;
  }

  async post(endpoint, body) {
    const response = await fetch(`${BASE_URL}${endpoint}`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(body)
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    // Invalidate related cache entries
    this.invalidateCache(endpoint);

    return await response.json();
  }

  async put(endpoint, body) {
    const response = await fetch(`${BASE_URL}${endpoint}`, {
      method: 'PUT',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(body)
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    // Invalidate related cache entries
    this.invalidateCache(endpoint);

    return await response.json();
  }

  invalidateCache(endpoint) {
    // Remove all cache entries for this endpoint
    const baseEndpoint = endpoint.split('/').slice(0, -1).join('/');
    for (const key of this.cache.keys()) {
      if (key.startsWith(baseEndpoint)) {
        this.cache.delete(key);
        console.log(`Invalidated cache for ${key}`);
      }
    }
  }

  clearCache() {
    this.cache.clear();
    console.log('Cache cleared');
  }
}

// Usage
const client = new CachedAPIClient(API_KEY);

// First call - fetches from API
const projects1 = await client.get('/projects');

// Second call within 5 minutes - returns cached data
const projects2 = await client.get('/projects');

// Create new project - invalidates cache
await client.post('/projects', {
  name: 'New Project',
  customer_id: 'cust_123'
});

// Next call fetches fresh data
const projects3 = await client.get('/projects');

Pattern 5: Bidirectional Sync (Preventing Echo Storms)

When syncing data between WorkSkedge and another system, prevent infinite update loops with proper tracking.

class BidirectionalSync {
  constructor(workskedgeAPI, externalAPI) {
    this.workskedgeAPI = workskedgeAPI;
    this.externalAPI = externalAPI;
    this.syncMap = new Map(); // Track synced records
    this.processingUpdates = new Set(); // Prevent echo storms
  }

  // Store mapping between WorkSkedge ID and external system ID
  storeSyncMapping(workskedgeId, externalId, lastSyncTime = null) {
    this.syncMap.set(workskedgeId, {
      externalId,
      lastSync: lastSyncTime || Date.now()
    });
  }

  getSyncMapping(workskedgeId) {
    return this.syncMap.get(workskedgeId);
  }

  // Handle webhook from WorkSkedge
  async handleWorkskedgeWebhook(event) {
    const workOrderId = event.data.id;

    // Check if we're currently processing an update for this record
    if (this.processingUpdates.has(workOrderId)) {
      console.log(`Ignoring echo for ${workOrderId}`);
      return;
    }

    // Mark as processing
    this.processingUpdates.add(workOrderId);

    try {
      const syncInfo = this.getSyncMapping(workOrderId);

      if (!syncInfo) {
        // New work order - create in external system
        const externalTicket = await this.externalAPI.createTicket({
          title: event.data.title,
          description: event.data.description,
          status: event.data.status
        });

        this.storeSyncMapping(workOrderId, externalTicket.id);
      } else {
        // Update existing ticket in external system
        await this.externalAPI.updateTicket(syncInfo.externalId, {
          title: event.data.title,
          description: event.data.description,
          status: event.data.status
        });

        this.storeSyncMapping(workOrderId, syncInfo.externalId);
      }
    } finally {
      // Remove from processing set after a delay
      setTimeout(() => {
        this.processingUpdates.delete(workOrderId);
      }, 5000); // 5 second cooldown
    }
  }

  // Handle webhook from external system
  async handleExternalWebhook(externalEvent) {
    const externalTicketId = externalEvent.ticket.id;

    // Find corresponding WorkSkedge work order
    let workOrderId = null;
    for (const [wsId, syncInfo] of this.syncMap.entries()) {
      if (syncInfo.externalId === externalTicketId) {
        workOrderId = wsId;
        break;
      }
    }

    if (!workOrderId) {
      console.log('No mapping found for external ticket');
      return;
    }

    // Check if we're currently processing an update
    if (this.processingUpdates.has(workOrderId)) {
      console.log(`Ignoring echo for ${workOrderId}`);
      return;
    }

    this.processingUpdates.add(workOrderId);

    try {
      // Update work order in WorkSkedge
      await this.workskedgeAPI.updateWorkOrder(workOrderId, {
        title: externalEvent.ticket.title,
        description: externalEvent.ticket.description,
        status: this.mapExternalStatus(externalEvent.ticket.status)
      });

      this.storeSyncMapping(workOrderId, externalTicketId);
    } finally {
      setTimeout(() => {
        this.processingUpdates.delete(workOrderId);
      }, 5000);
    }
  }

  mapExternalStatus(externalStatus) {
    const statusMap = {
      'open': 'scheduled',
      'in_progress': 'in_progress',
      'resolved': 'completed',
      'closed': 'completed'
    };
    return statusMap[externalStatus] || 'scheduled';
  }
}

// Usage
const sync = new BidirectionalSync(workskedgeClient, externalClient);

// Handle WorkSkedge webhook
app.post('/webhooks/workskedge', async (req, res) => {
  res.status(200).send('OK');
  await sync.handleWorkskedgeWebhook(req.body);
});

// Handle external system webhook
app.post('/webhooks/external', async (req, res) => {
  res.status(200).send('OK');
  await sync.handleExternalWebhook(req.body);
});

Pattern 6: Search and Filter

Use query parameters to filter and search for specific resources efficiently.

async function searchWorkOrders(filters) {
  const params = new URLSearchParams();

  // Add filters
  if (filters.status) params.append('status', filters.status);
  if (filters.priority) params.append('priority', filters.priority);
  if (filters.project_id) params.append('project_id', filters.project_id);
  if (filters.assigned_to) params.append('assigned_to', filters.assigned_to);
  if (filters.scheduled_after) params.append('scheduled_after', filters.scheduled_after);
  if (filters.scheduled_before) params.append('scheduled_before', filters.scheduled_before);

  // Pagination
  params.append('limit', filters.limit || 20);
  params.append('offset', filters.offset || 0);

  const response = await fetch(
    `${BASE_URL}/work-orders?${params.toString()}`,
    {
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      }
    }
  );

  if (!response.ok) {
    throw new Error(`Search failed: ${response.status}`);
  }

  return await response.json();
}

// Usage examples

// Find all high priority work orders
const highPriorityWorkOrders = await searchWorkOrders({
  priority: 'high',
  status: 'scheduled'
});

// Find work orders for a specific project
const projectWorkOrders = await searchWorkOrders({
  project_id: 'proj_123',
  scheduled_after: '2025-01-01'
});

// Find work orders assigned to a specific employee
const employeeWorkOrders = await searchWorkOrders({
  assigned_to: 'emp_abc123',
  status: 'in_progress'
});

Best Practices Summary

Next Steps

Understanding API Error Responses

WorkSkedge API returns standardized error responses with HTTP status codes and detailed error messages.

Error Response Format

{
  "error": {
    "type": "validation_error",
    "message": "Invalid project_id",
    "code": "invalid_parameter",
    "param": "project_id",
    "details": {
      "project_id": "Project 'proj_invalid' does not exist"
    }
  }
}

Exponential Backoff Strategy

Implement exponential backoff to handle temporary failures gracefully without overwhelming the API.

class RetryStrategy {
  constructor(options = {}) {
    this.maxRetries = options.maxRetries || 3;
    this.baseDelay = options.baseDelay || 1000; // 1 second
    this.maxDelay = options.maxDelay || 32000;  // 32 seconds
    this.retryableStatuses = new Set([429, 500, 502, 503, 504]);
  }

  shouldRetry(error, attemptNumber) {
    // Don't retry if max attempts reached
    if (attemptNumber >= this.maxRetries) {
      return false;
    }

    // Retry on network errors
    if (error.name === 'TypeError' || error.name === 'NetworkError') {
      return true;
    }

    // Retry on specific HTTP status codes
    if (error.status && this.retryableStatuses.has(error.status)) {
      return true;
    }

    return false;
  }

  getDelay(attemptNumber) {
    // Calculate exponential backoff: baseDelay * 2^attempt
    const exponentialDelay = this.baseDelay * Math.pow(2, attemptNumber);

    // Add jitter (random 0-25% of delay) to prevent thundering herd
    const jitter = Math.random() * exponentialDelay * 0.25;

    // Cap at maxDelay
    return Math.min(exponentialDelay + jitter, this.maxDelay);
  }

  async executeWithRetry(fn) {
    let lastError;

    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
      try {
        return await fn();
      } catch (error) {
        lastError = error;

        if (!this.shouldRetry(error, attempt)) {
          throw error;
        }

        const delay = this.getDelay(attempt);
        console.log(`Attempt ${attempt + 1} failed. Retrying in ${delay}ms...`);

        await new Promise(resolve => setTimeout(resolve, delay));
      }
    }

    throw lastError;
  }
}

// Usage
const retry = new RetryStrategy({
  maxRetries: 3,
  baseDelay: 1000
});

const projects = await retry.executeWithRetry(async () => {
  const response = await fetch('https://app.workskedge.com/api/v1/projects', {
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    }
  });

  if (!response.ok) {
    const error = new Error(`HTTP ${response.status}`);
    error.status = response.status;
    throw error;
  }

  return await response.json();
});

Rate Limit Handling

Handle rate limits by respecting the Retry-After header and implementing a request queue.

class RateLimitHandler {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.queue = [];
    this.processing = false;
    this.rateLimit = {
      remaining: 60,
      reset: Date.now() + 60000
    };
  }

  updateRateLimitInfo(headers) {
    this.rateLimit = {
      remaining: parseInt(headers.get('X-RateLimit-Remaining') || '60'),
      reset: parseInt(headers.get('X-RateLimit-Reset') || Date.now() + 60000)
    };
  }

  async waitForRateLimit() {
    if (this.rateLimit.remaining > 0) {
      return;
    }

    const waitTime = Math.max(0, this.rateLimit.reset - Date.now());
    console.log(`Rate limit reached. Waiting ${waitTime}ms...`);
    await new Promise(resolve => setTimeout(resolve, waitTime));
  }

  async request(endpoint, options = {}) {
    return new Promise((resolve, reject) => {
      this.queue.push({ endpoint, options, resolve, reject });
      this.processQueue();
    });
  }

  async processQueue() {
    if (this.processing || this.queue.length === 0) {
      return;
    }

    this.processing = true;

    while (this.queue.length > 0) {
      await this.waitForRateLimit();

      const { endpoint, options, resolve, reject } = this.queue.shift();

      try {
        const response = await fetch(endpoint, {
          ...options,
          headers: {
            'Authorization': `Bearer ${this.apiKey}`,
            'Content-Type': 'application/json',
            ...options.headers
          }
        });

        // Update rate limit info from response headers
        this.updateRateLimitInfo(response.headers);

        if (response.status === 429) {
          const retryAfter = response.headers.get('Retry-After');
          const waitTime = retryAfter ? parseInt(retryAfter) * 1000 : 60000;

          console.log(`Rate limited. Waiting ${waitTime}ms before retry...`);
          await new Promise(r => setTimeout(r, waitTime));

          // Re-queue the request
          this.queue.unshift({ endpoint, options, resolve, reject });
          continue;
        }

        if (!response.ok) {
          const error = await response.json();
          reject(new Error(error.message || `HTTP ${response.status}`));
          continue;
        }

        const data = await response.json();
        resolve(data);
      } catch (error) {
        reject(error);
      }
    }

    this.processing = false;
  }
}

// Usage
const handler = new RateLimitHandler(API_KEY);

// All requests automatically queued and rate limited
const project1 = await handler.request('https://app.workskedge.com/api/v1/projects/proj_1');
const project2 = await handler.request('https://app.workskedge.com/api/v1/projects/proj_2');
const project3 = await handler.request('https://app.workskedge.com/api/v1/projects/proj_3');

Comprehensive Error Handler

Combine retry logic, rate limit handling, and error classification into a single robust client.

class RobustAPIClient {
  constructor(apiKey, options = {}) {
    this.apiKey = apiKey;
    this.baseUrl = options.baseUrl || 'https://app.workskedge.com/api/v1';
    this.retryStrategy = new RetryStrategy(options.retry);
    this.rateLimitHandler = new RateLimitHandler(apiKey);
    this.errorCallbacks = [];
  }

  onError(callback) {
    this.errorCallbacks.push(callback);
  }

  notifyError(error, context) {
    this.errorCallbacks.forEach(callback => {
      try {
        callback(error, context);
      } catch (err) {
        console.error('Error in error callback:', err);
      }
    });
  }

  async request(endpoint, options = {}) {
    const url = `${this.baseUrl}${endpoint}`;
    const context = {
      endpoint,
      method: options.method || 'GET',
      timestamp: new Date().toISOString()
    };

    try {
      return await this.retryStrategy.executeWithRetry(async () => {
        return await this.rateLimitHandler.request(url, options);
      });
    } catch (error) {
      const enhancedError = this.enhanceError(error, context);
      this.notifyError(enhancedError, context);
      throw enhancedError;
    }
  }

  enhanceError(error, context) {
    const enhanced = {
      message: error.message,
      context,
      timestamp: new Date().toISOString(),
      retryable: false,
      userMessage: 'An error occurred'
    };

    if (error.status) {
      enhanced.status = error.status;

      switch (error.status) {
        case 400:
          enhanced.userMessage = 'Invalid request. Please check your input.';
          break;
        case 401:
          enhanced.userMessage = 'Authentication failed. Please check your API key.';
          break;
        case 403:
          enhanced.userMessage = 'Permission denied. Your API key lacks required permissions.';
          break;
        case 404:
          enhanced.userMessage = 'Resource not found.';
          break;
        case 422:
          enhanced.userMessage = 'Validation error. Please check your input.';
          break;
        case 429:
          enhanced.userMessage = 'Rate limit exceeded. Please try again later.';
          enhanced.retryable = true;
          break;
        case 500:
        case 502:
        case 503:
        case 504:
          enhanced.userMessage = 'Server error. Please try again later.';
          enhanced.retryable = true;
          break;
        default:
          enhanced.userMessage = `An error occurred (${error.status})`;
      }
    }

    return enhanced;
  }

  async get(endpoint, params = {}) {
    const queryString = new URLSearchParams(params).toString();
    const url = queryString ? `${endpoint}?${queryString}` : endpoint;
    return this.request(url, { method: 'GET' });
  }

  async post(endpoint, data) {
    return this.request(endpoint, {
      method: 'POST',
      body: JSON.stringify(data)
    });
  }

  async put(endpoint, data) {
    return this.request(endpoint, {
      method: 'PUT',
      body: JSON.stringify(data)
    });
  }

  async delete(endpoint) {
    return this.request(endpoint, { method: 'DELETE' });
  }
}

// Usage
const client = new RobustAPIClient(API_KEY);

// Register error handler
client.onError((error, context) => {
  console.error('API Error:', {
    message: error.message,
    status: error.status,
    endpoint: context.endpoint,
    retryable: error.retryable
  });

  // Send to error tracking service
  // errorTracker.captureException(error, { extra: context });

  // Show user-friendly message
  if (error.userMessage) {
    // displayNotification(error.userMessage);
  }
});

// Make requests with automatic retry and rate limiting
try {
  const projects = await client.get('/projects');
  console.log('Projects:', projects);
} catch (error) {
  console.error('Failed to fetch projects:', error.userMessage);
}

Circuit Breaker Pattern

Prevent cascading failures by implementing a circuit breaker that stops making requests after repeated failures.

class CircuitBreaker {
  constructor(options = {}) {
    this.failureThreshold = options.failureThreshold || 5;
    this.resetTimeout = options.resetTimeout || 60000; // 1 minute
    this.state = 'CLOSED'; // CLOSED, OPEN, HALF_OPEN
    this.failures = 0;
    this.lastFailureTime = null;
    this.successCount = 0;
  }

  async execute(fn) {
    // Check if circuit is open
    if (this.state === 'OPEN') {
      // Check if enough time has passed to try again
      if (Date.now() - this.lastFailureTime >= this.resetTimeout) {
        this.state = 'HALF_OPEN';
        console.log('Circuit breaker entering HALF_OPEN state');
      } else {
        throw new Error('Circuit breaker is OPEN. Service is unavailable.');
      }
    }

    try {
      const result = await fn();

      // Success - handle based on current state
      if (this.state === 'HALF_OPEN') {
        this.successCount++;

        // After 2 successful requests, close the circuit
        if (this.successCount >= 2) {
          this.reset();
          console.log('Circuit breaker CLOSED after successful requests');
        }
      } else {
        this.reset();
      }

      return result;
    } catch (error) {
      this.failures++;
      this.lastFailureTime = Date.now();

      // Trip the circuit if threshold exceeded
      if (this.failures >= this.failureThreshold) {
        this.state = 'OPEN';
        console.error(`Circuit breaker OPEN after ${this.failures} failures`);
      }

      throw error;
    }
  }

  reset() {
    this.failures = 0;
    this.successCount = 0;
    this.state = 'CLOSED';
  }

  getStatus() {
    return {
      state: this.state,
      failures: this.failures,
      lastFailureTime: this.lastFailureTime
    };
  }
}

// Usage with API client
class APIClientWithCircuitBreaker {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.circuitBreaker = new CircuitBreaker({
      failureThreshold: 5,
      resetTimeout: 60000
    });
  }

  async request(endpoint, options = {}) {
    return await this.circuitBreaker.execute(async () => {
      const response = await fetch(endpoint, {
        ...options,
        headers: {
          'Authorization': `Bearer ${this.apiKey}`,
          'Content-Type': 'application/json',
          ...options.headers
        }
      });

      if (!response.ok) {
        throw new Error(`HTTP ${response.status}`);
      }

      return await response.json();
    });
  }
}

const client = new APIClientWithCircuitBreaker(API_KEY);

// Circuit breaker protects against cascading failures
try {
  const data = await client.request('https://app.workskedge.com/api/v1/projects');
} catch (error) {
  if (error.message.includes('Circuit breaker is OPEN')) {
    console.log('Service temporarily unavailable. Please try again later.');
  }
}

Graceful Degradation

Implement fallback strategies to keep your application functional even when API requests fail.

class GracefulAPIClient {
  constructor(apiKey, cache) {
    this.apiKey = apiKey;
    this.cache = cache; // External cache (Redis, localStorage, etc.)
  }

  async getWithFallback(cacheKey, fetchFn, options = {}) {
    const {
      maxAge = 300000, // 5 minutes
      useStaleOnError = true
    } = options;

    try {
      // Try to fetch fresh data
      const data = await fetchFn();

      // Cache the successful response
      await this.cache.set(cacheKey, {
        data,
        timestamp: Date.now()
      });

      return {
        data,
        source: 'api',
        fresh: true
      };
    } catch (error) {
      console.error('API request failed:', error);

      if (!useStaleOnError) {
        throw error;
      }

      // Try to use cached data
      const cached = await this.cache.get(cacheKey);

      if (!cached) {
        throw new Error('No cached data available');
      }

      const age = Date.now() - cached.timestamp;
      const isStale = age > maxAge;

      if (isStale) {
        console.warn(`Using stale cached data (${Math.round(age / 1000)}s old)`);
      }

      return {
        data: cached.data,
        source: 'cache',
        fresh: false,
        age
      };
    }
  }

  async getProjects() {
    return this.getWithFallback(
      'projects',
      async () => {
        const response = await fetch(
          'https://app.workskedge.com/api/v1/projects',
          {
            headers: {
              'Authorization': `Bearer ${this.apiKey}`,
              'Content-Type': 'application/json'
            }
          }
        );

        if (!response.ok) {
          throw new Error(`HTTP ${response.status}`);
        }

        return await response.json();
      },
      {
        maxAge: 600000, // 10 minutes
        useStaleOnError: true
      }
    );
  }
}

// Simple in-memory cache implementation
class MemoryCache {
  constructor() {
    this.store = new Map();
  }

  async get(key) {
    return this.store.get(key);
  }

  async set(key, value) {
    this.store.set(key, value);
  }
}

// Usage
const cache = new MemoryCache();
const client = new GracefulAPIClient(API_KEY, cache);

const result = await client.getProjects();

if (result.fresh) {
  console.log('Showing fresh data from API');
} else {
  console.log(`Showing cached data (${Math.round(result.age / 1000)}s old)`);
  console.log('Note: Data may be outdated due to API unavailability');
}

Error Handling Best Practices

Next Steps