Webhooks

{
  "id": "evt_1NXWPnCo6bFb1KQto6C8OWvE",
  "object": "event",
  "api_version": "2024-01-01",
  "created": 1704067200,
  "type": "order.created",
  "data": {
    "object": {
      // Full resource object
    },
    "previous_attributes": {
      // For update events, previous values of changed fields
    }
  },
  "request": {
    "id": "req_abc123",
    "idempotency_key": "order-123"
  },
  "metadata": {
    "workspace_id": "ws_123",
    "user_id": "usr_456",
    "source": "api"
  }
}

class WebhookProcessor {
  constructor() {
    this.queue = new Queue('webhooks');
    this.processed = new Set();
  }
  
  async handle(event) {
    // 1. Check for duplicate processing
    if (this.processed.has(event.id)) {
      console.log(`Event ${event.id} already processed`);
      return { status: 'duplicate' };
    }
    
    // 2. Add to processing set
    this.processed.add(event.id);
    
    // 3. Queue for async processing
    await this.queue.add('process-webhook', {
      event,
      receivedAt: new Date().toISOString()
    });
    
    // 4. Return quickly
    return { status: 'queued' };
  }
  
  async process(job) {
    const { event } = job.data;
    
    try {
      // 5. Route to appropriate handler
      const handler = this.getHandler(event.type);
      if (!handler) {
        console.warn(`No handler for event type: ${event.type}`);
        return;
      }
      
      // 6. Process with retry logic
      await this.withRetry(() => handler(event.data.object));
      
      // 7. Mark as completed
      await this.markProcessed(event.id);
      
    } catch (error) {
      // 8. Handle errors
      console.error(`Failed to process webhook ${event.id}:`, error);
      
      // 9. Retry or dead letter
      if (job.attemptsMade < 3) {
        throw error; // Retry
      } else {
        await this.sendToDeadLetter(event, error);
      }
    }
  }
  
  getHandler(eventType) {
    const handlers = {
      'order.created': this.handleOrderCreated,
      'order.updated': this.handleOrderUpdated,
      'order.cancelled': this.handleOrderCancelled,
      'return.created': this.handleReturnCreated,
      'customer.created': this.handleCustomerCreated,
      'inventory.low_stock': this.handleLowStock,
      // Add more handlers
    };
    
    return handlers[eventType];
  }
  
  async handleOrderCreated(order) {
    // Send confirmation email
    await emailService.sendOrderConfirmation(order);
    
    // Update inventory
    await inventoryService.allocate(order.items);
    
    // Sync with ERP
    await erpService.createOrder(order);
    
    // Analytics
    await analytics.track('order_created', {
      order_id: order.id,
      value: order.totals.total,
      customer_id: order.customer.id
    });
  }
  
  async handleReturnCreated(return) {
    // Generate return label
    const label = await shippingService.createReturnLabel(return);
    
    // Email label to customer
    await emailService.sendReturnLabel(return, label);
    
    // Create support ticket
    await supportService.createTicket({
      type: 'return',
      return_id: return.id,
      customer_email: return.customer_email
    });
  }
  
  async withRetry(fn, maxRetries = 3) {
    for (let i = 0; i < maxRetries; i++) {
      try {
        return await fn();
      } catch (error) {
        if (i === maxRetries - 1) throw error;
        await new Promise(r => setTimeout(r, 1000 * Math.pow(2, i)));
      }
    }
  }
}

class IdempotentWebhookHandler {
  constructor(redis) {
    this.redis = redis;
  }
  
  async handle(event) {
    const key = `webhook:${event.id}`;
    const lockKey = `${key}:lock`;
    
    // Try to acquire lock
    const acquired = await this.redis.set(
      lockKey,
      '1',
      'NX',
      'EX',
      30 // 30 second lock
    );
    
    if (!acquired) {
      // Another process is handling this event
      return { status: 'processing' };
    }
    
    try {
      // Check if already processed
      const processed = await this.redis.get(key);
      if (processed) {
        return JSON.parse(processed);
      }
      
      // Process event
      const result = await this.processEvent(event);
      
      // Cache result
      await this.redis.setex(
        key,
        86400, // 24 hour TTL
        JSON.stringify(result)
      );
      
      return result;
      
    } finally {
      // Release lock
      await this.redis.del(lockKey);
    }
  }
}

app.post('/webhook', async (req, res) => {
  try {
    await processWebhook(req.body);
    res.status(200).json({ success: true });
  } catch (error) {
    if (error.type === 'VALIDATION_ERROR') {
      // Permanent failure - don't retry
      res.status(400).json({ error: error.message });
    } else {
      // Temporary failure - retry
      res.status(500).json({ error: 'Processing failed' });
    }
  }
});

curl -X POST https://api.stateset.com/v1/webhooks/simulate \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "order.created",
    "endpoint_url": "https://your-app.com/webhooks",
    "custom_data": {
      "order_id": "test_123"
    }
  }'

# Start your local server
npm run dev

# In another terminal, create tunnel
ngrok http 3000

# Configure webhook endpoint in StateSet dashboard
# https://abc123.ngrok.io/webhooks

// List webhook endpoints
const endpoints = await stateset.webhookEndpoints.list();

// Create webhook endpoint
const endpoint = await stateset.webhookEndpoints.create({
  url: 'https://your-app.com/webhooks',
  events: [
    'order.created',
    'order.updated',
    'return.created'
  ],
  description: 'Production webhook endpoint',
  metadata: {
    environment: 'production'
  }
});

// Update webhook endpoint
await stateset.webhookEndpoints.update(endpoint.id, {
  events: [...endpoint.events, 'customer.created']
});

// Delete webhook endpoint
await stateset.webhookEndpoints.delete(endpoint.id);

// Retrieve endpoint secret
const secret = await stateset.webhookEndpoints.getSecret(endpoint.id);

// Get webhook event logs
const logs = await stateset.webhookEvents.list({
  endpoint_id: 'we_123',
  limit: 100
});

logs.data.forEach(log => {
  console.log({
    event_id: log.event_id,
    status: log.status,
    attempts: log.attempts,
    last_error: log.last_error,
    next_retry: log.next_retry_at
  });
});

// Retry failed webhook
await stateset.webhookEvents.retry('evt_failed_123');

class WebhookMonitor {
  trackDelivery(event, success, duration) {
    metrics.increment('webhooks.delivered', {
      event_type: event.type,
      success: success
    });
    
    metrics.histogram('webhooks.duration', duration, {
      event_type: event.type
    });
    
    if (!success) {
      this.alertOnFailure(event);
    }
  }
  
  alertOnFailure(event) {
    if (this.getFailureRate() > 0.05) { // 5% failure rate
      alerts.send({
        severity: 'high',
        message: 'High webhook failure rate detected',
        details: {
          rate: this.getFailureRate(),
          event_type: event.type
        }
      });
    }
  }
}