Build custom feedback portals with UserVoice API and Webflow

UserVoice provides a REST API v2 and webhook capabilities that enable custom feedback portal implementations beyond what the standard widget offers.

This guide covers the API integration pattern—server-side proxy architecture, OAuth 2.0 authentication, webhook configuration, and CMS synchronization for building custom feedback experiences in Webflow. For simple widget embedding without server infrastructure, see the companion guide: Embed UserVoice feedback widgets in Webflow.

What this integration enables

The API integration pattern supports advanced use cases that require server-side processing:

• Custom feedback submission forms with your own UI design
• Displaying UserVoice data (suggestions, vote counts, statuses) in Webflow CMS
• Real-time updates via webhooks when ideas are submitted or status changes
• Single Sign-On (SSO) integration with your authentication system
• Programmatic suggestion creation and management
• Custom voting interfaces and feedback dashboards

Architecture overview

Custom implementations using the UserVoice Admin API require server-side proxy infrastructure due to two critical technical constraints:

1. Webflow client-side limitations: According to Custom code in head and body tags, Webflow only supports client-side JavaScript, HTML, and CSS—no server-side languages.
2. API credential security: The Component Architecture documentation explicitly warns: "Never include secrets in your component code. All JavaScript you write gets sent to the browser and is visible to your site visitors."

Your Webflow site communicates with a proxy server, which authenticates against the UserVoice Admin API using OAuth 2.0 Client Credentials flow. The proxy securely stores API credentials in environment variables and manages token acquisition and refresh.

Prerequisites

Set up your UserVoice account

1. Create a UserVoice account and set up a forum through the admin console settings
2. Generate API credentials in Admin Console under Settings → Integrations → UserVoice API keys
3. Create a "Trusted API Client" and check the "Trusted" checkbox as documented in the API Key documentation
4. Save your Client ID and Client Secret securely
5. Note your subdomain (the yourcompany portion of yourcompany.uservoice.com)

Configure your Webflow workspace

1. Ensure your workspace uses a plan that supports custom code
2. Verify you have Admin or Owner workspace permissions (required to register apps and manage API credentials)
3. For CMS synchronization, register an app in your workspace settings to generate Webflow OAuth credentials

Server-side proxy implementation

Hosting options

Implement a server-side proxy component using one of these approaches:

• Webflow Cloud (recommended for staying on-platform): Deploy a Next.js or Astro application alongside your Webflow site using Webflow Cloud. This approach is more complex than standalone serverless functions but keeps your entire stack within Webflow's ecosystem and eliminates separate hosting management.
• Standalone serverless functions: Use AWS Lambda, Cloudflare Workers, Vercel, or Netlify Functions for lightweight, cost-effective deployments.
• Traditional server infrastructure: For applications requiring more control over the runtime environment.

Proxy requirements

Your proxy must:

• Store UserVoice API credentials (Client ID and Client Secret) securely in environment variables
• Generate and cache OAuth 2.0 Client Credentials access tokens (valid for 7,200 seconds)
• Validate incoming requests originating from your Webflow domain
• Validate and allowlist requested resources to prevent arbitrary endpoint access
• Proxy authenticated requests to UserVoice Admin API v2 endpoints using Bearer token authorization
• Forward UserVoice API responses to the client while monitoring rate limit headers
• Implement exponential backoff retry logic for handling rate-limited responses (HTTP 429)

Configure CORS headers on your proxy to allow requests from your Webflow domain.

Authentication flow

UserVoice implements OAuth 2.0 Client Credentials for server-side applications. The flow:

1. Your proxy requests an access token by sending client credentials
2. UserVoice returns a bearer token valid for 7,200 seconds (2 hours)
3. Include the token in the Authorization: Bearer {token} header for all API requests

Token acquisition:

curl https://SUBDOMAIN.uservoice.com/api/v2/oauth/token \
  --data "grant_type=client_credentials&client_id=KEY&client_secret=SECRET"

Response:

{
  "access_token": "096e8ae9c6a3c039",
  "token_type": "bearer",
  "expires_in": 7200
}

Example proxy implementation

// Proxy implementation for serverless platforms (AWS Lambda/Vercel/Netlify)
// Note: Uses native fetch (Node.js v21+). For older Node versions, install node-fetch.

// Token cache (use Redis/DynamoDB in production for multi-instance deployments)
let cachedToken = null;
let tokenExpiry = 0;

// Endpoint allowlist - only these resources can be requested
// This prevents client-side code from accessing arbitrary API endpoints
const ALLOWED_RESOURCES = {
  'suggestions': '/api/v2/admin/suggestions',
  'forums': '/api/v2/admin/forums',
  'users': '/api/v2/admin/users',
  'comments': '/api/v2/admin/comments'
};

async function getAccessToken() {
  if (cachedToken && Date.now() < tokenExpiry) {
    return cachedToken;
  }
  
  const response = await fetch(
    `https://${process.env.USERVOICE_SUBDOMAIN}.uservoice.com/api/v2/oauth/token`,
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
      body: `grant_type=client_credentials&client_id=${process.env.USERVOICE_CLIENT_ID}&client_secret=${process.env.USERVOICE_CLIENT_SECRET}`
    }
  );
  
  const data = await response.json();
  cachedToken = data.access_token;
  tokenExpiry = Date.now() + (data.expires_in * 1000) - 60000; // Refresh 1 min early
  
  return cachedToken;
}

exports.handler = async (event) => {
  // Validate origin
  const origin = event.headers.origin || event.headers.Origin;
  const allowedOrigins = [
    'webflow.io',
    'yourdomain.com'  // Replace with your production domain
  ];
  
  const isAllowedOrigin = origin && allowedOrigins.some(domain => origin.includes(domain));
  if (!isAllowedOrigin) {
    return { statusCode: 403, body: JSON.stringify({ error: 'Forbidden' }) };
  }
  
  try {
    const { resource, method = 'GET', body } = JSON.parse(event.body);
    
    // Validate resource against allowlist
    const endpoint = ALLOWED_RESOURCES[resource];
    if (!endpoint) {
      return {
        statusCode: 400,
        body: JSON.stringify({ error: 'Invalid resource requested' })
      };
    }
    
    const token = await getAccessToken();
    
    // Proxy to UserVoice using validated endpoint
    const uvResponse = await fetch(
      `https://${process.env.USERVOICE_SUBDOMAIN}.uservoice.com${endpoint}`,
      {
        method,
        headers: {
          'Authorization': `Bearer ${token}`,
          'Content-Type': 'application/json'
        },
        body: body ? JSON.stringify(body) : undefined
      }
    );
    
    // Log rate limit status for monitoring
    const remaining = uvResponse.headers.get('X-Rate-Limit-Remaining');
    const limit = uvResponse.headers.get('X-Rate-Limit-Limit');
    if (remaining && parseInt(remaining, 10) < 10) {
      console.warn(`Rate limit warning: ${remaining}/${limit} requests remaining`);
    }
    
    const data = await uvResponse.json();
    
    return {
      statusCode: uvResponse.status,
      headers: {
        'Access-Control-Allow-Origin': origin,
        'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(data)
    };
    
  } catch (error) {
    console.error('Proxy error:', error.message);
    
    return {
      statusCode: 502,
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ 
        error: 'Integration error', 
        message: error.message 
      })
    };
  }
};