Guides

Advanced Integrations

Unlock the full potential of FeedbackKit with advanced integration patterns, custom workflows, and enterprise features for complex use cases.

Webhook Events

Real-time event notifications

Data Sync

Bidirectional data synchronization

Custom Workflows

Complex automation pipelines

Enterprise SSO

Single sign-on integration

Webhook Integration

Webhook Setup

Configure webhooks for real-time event notifications

import { FeedbackKitClient } from '@feedbackkit/widget';

const feedbackkit = new FeedbackKitClient({
  apiKey: 'fk_live_xxx'
});

// Create webhook endpoint
await feedbackkit.webhooks.create({
  url: 'https://yourapi.com/webhooks/feedbackkit',
  events: [
    'feedback.created',
    'feedback.updated', 
    'feedback.commented',
    'project.created'
  ],
  filters: {
    projectId: 'proj_abc123',
    // Additional filters
    metadata: {
      priority: 'high'
    }
  },
  headers: {
    'Authorization': 'Bearer your-internal-token',
    'X-Source': 'feedbackkit-webhook'
  },
  retryPolicy: {
    maxRetries: 3,
    backoffMultiplier: 2,
    initialDelay: 1000
  },
  active: true
});

// List existing webhooks
const webhooks = await feedbackkit.webhooks.list();
console.log('Active webhooks:', webhooks);

// Update webhook configuration
await feedbackkit.webhooks.update(webhookId, {
  events: ['feedback.created', 'feedback.updated'],
  active: true
});

// Test webhook delivery
await feedbackkit.webhooks.test(webhookId, {
  event: 'feedback.created',
  payload: {
    type: 'bug',
    priority: 'high',
    title: 'Test feedback'
  }
});

Data Synchronization

Database Integration

Sync FeedbackKit data with your existing database systems

// Sync feedback to your database
import { PrismaClient } from '@prisma/client';

const prisma = new PrismaClient();
const feedbackkit = new FeedbackKitClient({ apiKey: 'fk_live_xxx' });

// Bidirectional sync function
async function syncFeedbackData() {
  try {
    // Get recent feedback from FeedbackKit
    const recentFeedback = await feedbackkit.feedback.list('proj_abc123', {
      since: new Date(Date.now() - 24 * 60 * 60 * 1000), // Last 24h
      limit: 100
    });
    
    // Sync to local database
    for (const item of recentFeedback) {
      await prisma.feedbackEntry.upsert({
        where: { feedbackkitId: item.id },
        update: {
          type: item.type,
          priority: item.priority,
          title: item.title,
          description: item.description,
          updatedAt: new Date()
        },
        create: {
          feedbackkitId: item.id,
          type: item.type,
          priority: item.priority,
          title: item.title,
          description: item.description,
          metadata: item.metadata,
          createdAt: item.createdAt
        }
      });
    }
    
    // Sync local updates back to FeedbackKit
    const localUpdates = await prisma.feedbackEntry.findMany({
      where: {
        needsSync: true
      }
    });
    
    for (const entry of localUpdates) {
      if (entry.shouldNotify) {
        await feedbackkit.feedback.update(entry.feedbackkitId, {
          status: entry.status,
          assignee: entry.assignee
        });
      }
      
      // Mark as synced
      await prisma.feedbackEntry.update({
        where: { id: entry.id },
        data: { needsSync: false }
      });
    }
    
    console.log(`Synced ${recentFeedback.length} entries`);
  } catch (error) {
    console.error('Sync failed:', error);
  }
}

// Run sync every 5 minutes
setInterval(syncFeedbackData, 5 * 60 * 1000);

CRM Integration

Connect with popular CRM systems like Salesforce, HubSpot

// HubSpot integration
const hubspot = require('@hubspot/api-client');

const hubspotClient = new hubspot.Client({
  accessToken: process.env.HUBSPOT_ACCESS_TOKEN
});

async function syncToHubSpot(waitlistData) {
  try {
    // Create or update contact
    const contactObj = {
      properties: {
        email: waitlistData.email,
        firstname: waitlistData.metadata.name,
        waitlist_position: waitlistData.position,
        waitlist_signup_date: waitlistData.createdAt,
        lead_source: 'waitlist',
        lifecycle_stage: 'lead'
      }
    };
    
    const contact = await hubspotClient.crm.contacts.basicApi.create(contactObj);
    
    // Add to specific list
    await hubspotClient.crm.lists.membershipsApi.add(
      'waitlist-leads', // List ID
      [contact.id]
    );
    
    // Create deal if high-value prospect
    if (waitlistData.metadata.company_size === 'enterprise') {
      await hubspotClient.crm.deals.basicApi.create({
        properties: {
          dealname: `Waitlist Lead - ${waitlistData.email}`,
          amount: 50000,
          pipeline: 'default',
          dealstage: 'appointmentscheduled'
        },
        associations: [
          {
            to: { id: contact.id },
            types: [{ associationCategory: 'HUBSPOT_DEFINED', associationTypeId: 3 }]
          }
        ]
      });
    }
    
    console.log('Synced to HubSpot:', contact.id);
  } catch (error) {
    console.error('HubSpot sync failed:', error);
  }
}

Custom Workflows

Multi-Step Automation

Create complex automation workflows that span multiple systems

// Advanced workflow engine
class PromoWorkflow {
  constructor(promo, config) {
    this.promo = promo;
    this.config = config;
    this.steps = [];
  }
  
  // Define workflow steps
  addStep(name, condition, action) {
    this.steps.push({ name, condition, action });
    return this;
  }
  
  // Execute workflow
  async execute(trigger, data) {
    console.log(`Executing workflow for trigger: ${trigger}`);
    
    for (const step of this.steps) {
      try {
        // Check if step condition is met
        if (await step.condition(data)) {
          console.log(`Executing step: ${step.name}`);
          data = await step.action(data);
        }
      } catch (error) {
        console.error(`Step ${step.name} failed:`, error);
        if (step.required) throw error;
      }
    }
    
    return data;
  }
}

// Example: VIP Customer Workflow
const vipWorkflow = new PromoWorkflow(promo, {
  name: 'VIP Customer Journey',
  description: 'Special handling for enterprise prospects'
})
.addStep('Identify VIP', 
  // Condition: Check if enterprise prospect
  async (data) => {
    return data.metadata?.company_size === 'enterprise' || 
           data.metadata?.revenue > 1000000;
  },
  // Action: Tag as VIP and notify sales
  async (data) => {
    await promo.waitlist.update(data.id, {
      tags: [...(data.tags || []), 'vip', 'enterprise']
    });
    
    await slack.send({
      channel: '#sales',
      text: `🚨 VIP prospect joined waitlist: ${data.email}`,
      attachments: [{
        fields: [
          { title: 'Company', value: data.metadata.company },
          { title: 'Position', value: data.position },
          { title: 'Revenue', value: data.metadata.revenue }
        ]
      }]
    });
    
    return { ...data, vip: true };
  }
)
.addStep('Priority Placement',
  // Condition: VIP flag set
  async (data) => data.vip === true,
  // Action: Move to top 10% of waitlist
  async (data) => {
    const totalCount = await promo.waitlist.getStats(data.projectId);
    const newPosition = Math.min(data.position, Math.ceil(totalCount.total * 0.1));
    
    await promo.waitlist.updatePosition(data.id, newPosition);
    
    return { ...data, position: newPosition };
  }
)
.addStep('Custom Onboarding',
  // Condition: Always for VIPs
  async (data) => data.vip === true,
  // Action: Send personalized email and schedule call
  async (data) => {
    await sendEmail({
      to: data.email,
      template: 'vip-welcome',
      data: {
        name: data.metadata.name,
        company: data.metadata.company,
        position: data.position
      }
    });
    
    // Schedule sales call
    await calendly.scheduleCall({
      email: data.email,
      type: 'enterprise-demo',
      priority: 'high'
    });
    
    return data;
  }
);

// Trigger workflow on waitlist signup
promo.webhooks.on('waitlist.signup', async (data) => {
  await vipWorkflow.execute('waitlist.signup', data);
});

Enterprise Features

Single Sign-On (SSO)

Configure SAML/OIDC for enterprise authentication

// SAML SSO Configuration
await promo.enterprise.configureSAML({
  organizationId: 'org_enterprise_123',
  entityId: 'https://yourcompany.com/saml/metadata',
  ssoUrl: 'https://yourcompany.com/saml/sso',
  certificate: process.env.SAML_CERTIFICATE,
  attributeMapping: {
    email: 'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress',
    name: 'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name',
    department: 'http://schemas.yourcompany.com/claims/department'
  },
  roleMapping: {
    admin: ['PromoAdmin', 'TechLead'],
    member: ['Employee'],
    viewer: ['Contractor']
  }
});

// OIDC Configuration
await promo.enterprise.configureOIDC({
  organizationId: 'org_enterprise_123',
  issuer: 'https://yourcompany.okta.com',
  clientId: process.env.OIDC_CLIENT_ID,
  clientSecret: process.env.OIDC_CLIENT_SECRET,
  scopes: ['openid', 'profile', 'email', 'groups'],
  claimsMapping: {
    email: 'email',
    name: 'name',
    groups: 'groups'
  }
});

API Rate Limiting

Configure custom rate limits for high-volume usage

// Enterprise rate limiting
await promo.enterprise.configureRateLimits({
  organizationId: 'org_enterprise_123',
  limits: {
    // Per-endpoint limits
    'waitlist.create': {
      requests: 10000,
      window: '1h',
      burst: 100
    },
    'testimonial.submit': {
      requests: 5000,
      window: '1h',
      burst: 50
    },
    'changelog.create': {
      requests: 100,
      window: '1h',
      burst: 10
    }
  },
  
  // IP-based limits
  ipLimits: {
    requests: 100000,
    window: '1h'
  },
  
  // User-based limits
  userLimits: {
    requests: 50000,
    window: '1h'
  },
  
  // Custom limits by project
  projectLimits: {
    'proj_high_volume': {
      requests: 50000,
      window: '1h'
    }
  }
});

// Monitor rate limit usage
const usage = await promo.enterprise.getRateLimitUsage({
  organizationId: 'org_enterprise_123',
  timeframe: '24h'
});

console.log('API Usage:', usage);

Real-World Examples

SaaS Product Launch

Complete integration for a B2B SaaS launch campaign

// Complete SaaS launch integration
class SaaSLaunchIntegration {
  constructor() {
    this.promo = new FeedbackKitClient({ apiKey: process.env.PROMO_API_KEY });
    this.hubspot = new HubSpotClient({ accessToken: process.env.HUBSPOT_TOKEN });
    this.stripe = new Stripe(process.env.STRIPE_SECRET_KEY);
    this.sendgrid = new SendGrid(process.env.SENDGRID_API_KEY);
  }
  
  async setupIntegration() {
    // 1. Configure waitlist with referral rewards
    await this.promo.waitlist.configure('proj_saas_launch', {
      referralReward: 'Skip 50 spots + 3 months free',
      milestones: [100, 500, 1000, 5000],
      segmentation: {
        enterprise: { companySize: '500+', budget: 'enterprise' },
        smb: { companySize: '50-500', budget: 'professional' },
        startup: { companySize: '1-50', budget: 'starter' }
      }
    });
    
    // 2. Setup webhook handlers
    await this.promo.webhooks.create({
      url: 'https://api.ourcompany.com/webhooks/promo',
      events: ['waitlist.signup', 'waitlist.milestone'],
      handlers: {
        'waitlist.signup': this.handleSignup.bind(this),
        'waitlist.milestone': this.handleMilestone.bind(this)
      }
    });
    
    // 3. Configure testimonial collection
    await this.promo.testimonials.configure('prod_saas_app', {
      autoRequest: {
        trigger: 'usage_milestone',
        delay: '14d',
        conditions: {
          minUsage: 50,
          satisfaction: 4
        }
      },
      moderation: {
        autoApprove: { rating: 5, verified: true },
        flagKeywords: ['bug', 'broken', 'terrible']
      }
    });
  }
  
  async handleSignup(data) {
    const { email, metadata, position } = data;
    
    // 1. Add to HubSpot CRM
    const contact = await this.hubspot.crm.contacts.basicApi.create({
      properties: {
        email,
        firstname: metadata.name,
        company: metadata.company,
        waitlist_position: position,
        lead_source: 'waitlist',
        lifecycle_stage: metadata.companySize === '500+' ? 'sql' : 'mql'
      }
    });
    
    // 2. Create Stripe customer for future billing
    const customer = await this.stripe.customers.create({
      email,
      name: metadata.name,
      metadata: {
        hubspot_id: contact.id,
        waitlist_position: position,
        referral_code: data.referralCode
      }
    });
    
    // 3. Send welcome email sequence
    await this.sendgrid.send({
      to: email,
      templateId: 'd-welcome-sequence',
      dynamicTemplateData: {
        name: metadata.name,
        position,
        referralCode: data.referralCode,
        estimatedLaunch: this.getEstimatedLaunch(position)
      }
    });
    
    // 4. Notify sales team for enterprise prospects
    if (metadata.companySize === '500+') {
      await this.notifySalesTeam(contact, data);
    }
  }
  
  async handleMilestone(data) {
    const { milestone, totalSignups } = data;
    
    // Social proof campaigns
    if (milestone === 1000) {
      await this.sendgrid.send({
        to: 'all-subscribers',
        templateId: 'd-milestone-1k',
        dynamicTemplateData: {
          milestone: '1,000',
          socialProof: 'Join 1,000+ others waiting for launch'
        }
      });
      
      // Update website banner
      await this.updateWebsiteBanner('1,000+ people already signed up!');
    }
    
    // Media outreach
    if (milestone === 5000) {
      await this.triggerMediaOutreach();
    }
  }
}

// Initialize integration
const integration = new SaaSLaunchIntegration();
await integration.setupIntegration();

Next Steps

Setup Webhooks

Configure real-time event notifications

Connect Systems

Integrate with your existing tools

Build Workflows

Create custom automation pipelines