Webflow Core Workflow B — Sites, Pages, Forms & Ecommerce

Overview

Beyond CMS content management, Webflow's Data API v2 covers site operations, page

metadata, form submissions, ecommerce (products, orders, inventory), and custom code

injection. This skill covers all non-CMS API domains.

Prerequisites

• Completed webflow-install-auth setup
• Scopes needed: sites:read, sites:write, pages:read, forms:read,

ecommerce:read, ecommerce:write, customcode:read, customcode:write

Instructions

1. Sites Management

import { WebflowClient } from "webflow-api";

const webflow = new WebflowClient({
  accessToken: process.env.WEBFLOW_API_TOKEN!,
});

// List all sites
async function listSites() {
  const { sites } = await webflow.sites.list();
  for (const site of sites!) {
    console.log(`${site.displayName} (${site.id})`);
    console.log(`  Short name: ${site.shortName}`);
    console.log(`  Timezone: ${site.timeZone}`);
    console.log(`  Created: ${site.createdOn}`);
    console.log(`  Last published: ${site.lastPublished}`);
    console.log(`  Custom domains: ${site.customDomains?.map(d => d.url).join(", ")}`);
    console.log(`  Default locale: ${site.locales?.[0]?.displayName}`);
  }
}

// Get single site details
async function getSite(siteId: string) {
  const site = await webflow.sites.get(siteId);
  return site;
}

// Publish site (rate limit: 1 per minute)
async function publishSite(siteId: string, domains?: string[]) {
  await webflow.sites.publish(siteId, {
    publishToWebflowSubdomain: true,
    customDomains: domains, // Optional: publish to specific domains
  });
  console.log("Site published successfully");
}

2. Pages API

// List all pages for a site
async function listPages(siteId: string) {
  const { pages } = await webflow.pages.list(siteId);

  for (const page of pages!) {
    console.log(`${page.title} (${page.id})`);
    console.log(`  Slug: ${page.slug}`);
    console.log(`  SEO title: ${page.seo?.title}`);
    console.log(`  SEO description: ${page.seo?.description}`);
    console.log(`  Open Graph image: ${page.openGraph?.titleCopied}`);
    console.log(`  Created: ${page.createdOn}`);
    console.log(`  Published: ${page.publishedPath}`);
  }
}

// Get page metadata
async function getPage(pageId: string) {
  const page = await webflow.pages.getMetadata(pageId);
  return page;
}

// Update page SEO metadata
async function updatePageSEO(pageId: string) {
  await webflow.pages.updatePageSettings(pageId, {
    seo: {
      title: "New SEO Title — My Site",
      description: "Updated meta description for search engines.",
    },
    openGraph: {
      title: "New OG Titl

Webflow Cost Tuning

Overview

Optimize Webflow costs through smart plan selection, CDN-cached reads, bulk endpoint

usage, and proactive API usage monitoring. The biggest lever: **CDN-cached live item

reads are free and unlimited** — shift reads to the Content Delivery API.

Prerequisites

• Access to Webflow dashboard (billing section)
• Understanding of your integration's read/write patterns
• webflow-api SDK configured

Webflow Pricing Context

Site Plans (affect API limits)

Ecommerce Plans (additional)

Workspace Plans (affect developer access)

Instructions

Strategy 1: Shift Reads to CDN (Free and Unlimited)

The single biggest cost reduction: use the Content Delivery API for reads.

// EXPENSIVE: Staged item reads count against rate limits
const { items } = await webflow.collections.items.listItems(collectionId);

// FREE: CDN-cached live item reads have no rate limits
const { items } = await webflow.collections.items.listItemsLive(collectionId);

For public-facing content (blogs, product pages, team members), always use live

item endpoints. Only use staged endpoints when you need draft items.

Strategy 2: Bulk Endpoints (100x Fewer API Calls)

// EXPENSIVE: 1000 items = 1000 API calls
for (const item of items) {
  await webflow.collections.items.createItem(collectionId, { fieldData: item });
}

// CHEAP: 1000 items = 10 API 

Webflow Data Handling

Overview

Handle sensitive data correctly when working with the Webflow Data API v2. Covers

PII in form submissions, ecommerce customer data, CMS content classification,

GDPR/CCPA compliance patterns, and data retention policies.

Prerequisites

• Understanding of GDPR/CCPA requirements
• Webflow API token with forms:read, ecommerce:read scopes
• Database for audit logging
• Scheduled job infrastructure for data cleanup

Webflow Data Classification

Instructions

Step 1: PII Detection in Form Submissions

const PII_PATTERNS = [
  { type: "email", regex: /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g },
  { type: "phone", regex: /\b\d{3}[-.]?\d{3}[-.]?\d{4}\b/g },
  { type: "ssn", regex: /\b\d{3}-\d{2}-\d{4}\b/g },
  { type: "credit_card", regex: /\b\d{4}[- ]?\d{4}[- ]?\d{4}[- ]?\d{4}\b/g },
];

function detectPII(text: string): Array<{ type: string; found: boolean }> {
  return PII_PATTERNS.map(p => ({
    type: p.type,
    found: p.regex.test(text),
  })).filter(r => r.found);
}

// Scan form submissions for PII before logging
async function processFormSubmission(formId: string) {
  const { formSubmissions } = await webflow.forms.listSubmissions(formId);

  for (const sub of formSubmissions || []) {
    const rawData = JSON.stringify(sub.formData);
    const piiFindings = detectPII(rawData);

    if (piiFindings.length > 0) {
      console.warn(`PII detected in submission ${sub.id}: ${piiFindings.map(f => f.type).join(", ")}`);
      // Log redacted version only
      console.log("Form data:", redactPII(sub.formData || {}));
    }
  }
}

Step 2: PII Redaction

function redactPII(data: Record<string, any>): Record<string, any> {
  const sensitiveFields = new Set([
    "email", "phone", "telephone", "mobile", "ssn",
    "password", "credit-card", "card-number", "address",
    "full-name", "f

Webflow Debug Bundle

Overview

Collect comprehensive diagnostic information for Webflow integration troubleshooting.

Generates a support-ready bundle with SDK version, token status, rate limits, site

health, and redacted configuration.

Prerequisites

• webflow-api SDK installed
• Access to application logs
• Permission to run diagnostic commands

Instructions

Step 1: Debug Bundle Script

#!/bin/bash
# webflow-debug-bundle.sh
set -euo pipefail

BUNDLE_DIR="webflow-debug-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE_DIR"

echo "=== Webflow Debug Bundle ===" | tee "$BUNDLE_DIR/summary.txt"
echo "Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ)" | tee -a "$BUNDLE_DIR/summary.txt"
echo "" >> "$BUNDLE_DIR/summary.txt"

# --- Environment ---
echo "--- Environment ---" >> "$BUNDLE_DIR/summary.txt"
echo "Node.js: $(node --version 2>/dev/null || echo 'not found')" >> "$BUNDLE_DIR/summary.txt"
echo "npm: $(npm --version 2>/dev/null || echo 'not found')" >> "$BUNDLE_DIR/summary.txt"
echo "OS: $(uname -s) $(uname -r)" >> "$BUNDLE_DIR/summary.txt"
echo "WEBFLOW_API_TOKEN: ${WEBFLOW_API_TOKEN:+[SET]}${WEBFLOW_API_TOKEN:-[NOT SET]}" >> "$BUNDLE_DIR/summary.txt"
echo "WEBFLOW_SITE_ID: ${WEBFLOW_SITE_ID:+[SET]}${WEBFLOW_SITE_ID:-[NOT SET]}" >> "$BUNDLE_DIR/summary.txt"

# --- SDK Version ---
echo "" >> "$BUNDLE_DIR/summary.txt"
echo "--- SDK Version ---" >> "$BUNDLE_DIR/summary.txt"
npm list webflow-api 2>/dev/null >> "$BUNDLE_DIR/summary.txt" || echo "webflow-api: not installed" >> "$BUNDLE_DIR/summary.txt"
echo "Latest available: $(npm view webflow-api version 2>/dev/null || echo 'unknown')" >> "$BUNDLE_DIR/summary.txt"

# --- API Connectivity ---
echo "" >> "$BUNDLE_DIR/summary.txt"
echo "--- API Connectivity ---" >> "$BUNDLE_DIR/summary.txt"

if [ -n "${WEBFLOW_API_TOKEN:-}" ]; then
  # Token validation (list sites)
  HTTP_CODE=$(curl -s -o "$BUNDLE_DIR/sites-response.json" -w "%{http_code}" \
    -H "Authorization: Bearer $WEBFLOW_API_TOKEN" \
    https://api.webflow.com/v2/sites 2>/dev/null)
  echo "Sites endpoint: HTTP $HTTP_CODE" >> "$BUNDLE_DIR/summary.txt"

  if [ "$HTTP_CODE" = "200" ]; then
    SITE_COUNT=$(cat "$BUNDLE_DIR/sites-response.json" | python3 -c "import sys,json; print(len(json.load(sys.stdin).get('sites',[])))" 2>/dev/null || echo "parse error")
  

Webflow Deploy Integration

Overview

Deploy Webflow Data API v2 integrations to Vercel, Fly.io, or Google Cloud Run

with secure token management, health checks, and webhook endpoint configuration.

Prerequisites

• Working Webflow integration (tested locally)
• Production API token with minimal scopes
• Platform CLI installed (vercel, fly, or gcloud)

Instructions

Vercel Deployment

# Store Webflow secrets in Vercel
vercel env add WEBFLOW_API_TOKEN production
vercel env add WEBFLOW_SITE_ID production
vercel env add WEBFLOW_WEBHOOK_SECRET production

# Link and deploy
vercel link
vercel --prod

// vercel.json
{
  "env": {
    "WEBFLOW_API_TOKEN": "@webflow-api-token",
    "WEBFLOW_SITE_ID": "@webflow-site-id"
  },
  "functions": {
    "api/**/*.ts": {
      "maxDuration": 30
    }
  },
  "headers": [
    {
      "source": "/api/webhooks/webflow",
      "headers": [
        { "key": "Access-Control-Allow-Origin", "value": "https://api.webflow.com" }
      ]
    }
  ]
}

Vercel serverless function for webhook endpoint:

// api/webhooks/webflow.ts (Vercel Edge/Serverless)
import type { VercelRequest, VercelResponse } from "@vercel/node";
import crypto from "crypto";

export default async function handler(req: VercelRequest, res: VercelResponse) {
  if (req.method !== "POST") {
    return res.status(405).json({ error: "Method not allowed" });
  }

  // Verify webhook signature
  const signature = req.headers["x-webflow-signature"] as string;
  const rawBody = JSON.stringify(req.body);
  const expected = crypto
    .createHmac("sha256", process.env.WEBFLOW_WEBHOOK_SECRET!)
    .update(rawBody)
    .digest("hex");

  if (signature !== expected) {
    return res.status(401).json({ error: "Invalid signature" });
  }

  const { triggerType, payload } = req.body;
  console.log(`Webhook received: ${triggerType}`);

  // Handle different trigger types
  switch (triggerType) {
    case "form_submission":
      await handleFormSubmission(payload);
      break;
    case "ecomm_new_order":
      await handleNewOrder(payload);
      break;
    case "site_publish":
      await handleSitePublish(payload);
      break;
  }

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

Fly.io Deployment

# fly.toml
app = "my-webflow-app"
primary_region = "iad"

[env]
  NODE_ENV = "production"
  PORT = "3000"

[http_service]
  internal_port = 3000
  force_https = true
  auto_stop_machi

Webflow Enterprise RBAC

Overview

Enterprise-grade access control for Webflow Data API v2 integrations. Uses Webflow's

OAuth 2.0 scope system, per-site token isolation, and application-level RBAC to

enforce least privilege across teams and environments.

Prerequisites

• Webflow workspace (Core plan or higher for multiple members)
• OAuth 2.0 Data Client App (for user-authorized access)
• Understanding of Webflow scopes

Webflow's Native Access Model

Webflow provides three levels of access control:

Scope-Based Permission Model

Webflow scopes map directly to API access:

Instructions

Step 1: Define Application Roles

Map your application roles to Webflow scope sets:

enum AppRole {
  ContentViewer = "content_viewer",
  ContentEditor = "content_editor",
  SiteAdmin = "site_admin",
  EcommerceManager = "ecommerce_manager",
  FormProcessor = "form_processor",
}

// Map roles to required Webflow OAuth scopes
const ROLE_SCOPES: Record<AppRole, string[]> = {
  [AppRole.ContentViewer]: ["sites:read", "cms:read", "pages:read"],
  [AppRole.ContentEditor]: ["sites:read", "cms:read", "cms:write", "pages:read"],
  [AppRole.SiteAdmin]: [
    "sites:read",

Webflow Hello World

Overview

Minimal working examples demonstrating the three core Webflow Data API v2 operations:

listing sites, reading CMS collections/items, and creating a CMS item.

Prerequisites

• Completed webflow-install-auth setup
• webflow-api package installed
• Valid API token with sites:read and cms:read scopes

Instructions

Step 1: List Your Sites

Every Webflow API call starts with a site_id. List your sites to find it:

// hello-webflow.ts
import { WebflowClient } from "webflow-api";

const webflow = new WebflowClient({
  accessToken: process.env.WEBFLOW_API_TOKEN!,
});

async function listSites() {
  const { sites } = await webflow.sites.list();

  for (const site of sites!) {
    console.log(`${site.displayName}`);
    console.log(`  ID: ${site.id}`);
    console.log(`  Short name: ${site.shortName}`);
    console.log(`  Custom domains: ${site.customDomains?.map(d => d.url).join(", ")}`);
    console.log(`  Last published: ${site.lastPublished}`);
    console.log(`  Locales: ${site.locales?.map(l => l.displayName).join(", ")}`);
  }
}

listSites().catch(console.error);

Step 2: List CMS Collections

Collections define your content types (blog posts, team members, products, etc.):

async function listCollections(siteId: string) {
  const { collections } = await webflow.collections.list(siteId);

  for (const col of collections!) {
    console.log(`Collection: ${col.displayName}`);
    console.log(`  ID: ${col.id}`);
    console.log(`  Slug: ${col.slug}`);
    console.log(`  Item count: ${col.itemCount}`);
    console.log(`  Fields:`);
    for (const field of col.fields || []) {
      console.log(`    - ${field.displayName} (${field.type}, required: ${field.isRequired})`);
    }
  }
}

// Usage: pass your site_id
listCollections("your-site-id").catch(console.error);

Step 3: Read CMS Items

Fetch items from a collection — staged (draft) or live (published):

async function readItems(collectionId: string) {
  // Get staged (draft + published) items
  const { items } = await webflow.collections.items.listItems(collectionId, {
    limit: 10,
    offset: 0,
  });

  for (const item of items!) {
    console.log(`Item: ${item.fieldData?.name || item.id}`);
    console.log(`  ID: ${item.id}`);
    console.log(`  Slug: ${item.fieldData?.slug}`);
    console.log(`  Draft: ${item.isDraft}`);
    console.log(`  Archived: ${item.isArchived}`);
    console.log(`  Created: ${item.createdOn}`);
  }

  // Get live (published) items only
  const live = await webflow.collections.items.listItemsLive(collectionId, {
    limit: 10,
  });
  console.log(`\nLive items: ${live.items?.length}`);
}
<

Webflow Incident Runbook

Overview

Rapid incident response procedures for Webflow Data API v2 integration failures.

Covers triage, immediate remediation by error type, graceful degradation,

stakeholder communication, and postmortem.

Prerequisites

• Access to Webflow dashboard and status page
• Application logs and metrics access
• Communication channels (Slack, PagerDuty)
• Cached fallback data available

Severity Levels

Quick Triage (Run First)

#!/bin/bash
echo "=== Webflow Incident Triage ==="
echo "Time: $(date -u)"

# 1. Webflow platform status
echo ""
echo "--- Platform Status ---"
curl -s https://status.webflow.com/api/v2/status.json 2>/dev/null | \
  python3 -c "
import sys,json
d=json.load(sys.stdin)
print(f'Status: {d[\"status\"][\"description\"]}')
for c in d.get('components',[]):
  if c['status'] != 'operational':
    print(f'  DEGRADED: {c[\"name\"]} ({c[\"status\"]})')
" 2>/dev/null || echo "Cannot reach status page"

# 2. API connectivity
echo ""
echo "--- API Connectivity ---"
HTTP=$(curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $WEBFLOW_API_TOKEN" \
  https://api.webflow.com/v2/sites 2>/dev/null)
echo "Sites endpoint: HTTP $HTTP"

# 3. Rate limit status
echo ""
echo "--- Rate Limits ---"
curl -sI -H "Authorization: Bearer $WEBFLOW_API_TOKEN" \
  https://api.webflow.com/v2/sites 2>/dev/null | \
  grep -i "x-ratelimit\|retry-after" || echo "No rate limit headers"

# 4. Our health endpoint
echo ""
echo "--- App Health ---"
HEALTH=$(curl -s https://your-app.com/api/health 2>/dev/null)
echo "$HEALTH" | python3 -c "
import sys,json
d=json.load(sys.stdin)
print(f'Status: {d[\"status\"]}')
for k,v in d.get('services',{}).items():
  print(f'  {k}: {v.get(\"status\",\"unknown\")} ({v.get(\"latencyMs\",\"?\")}ms)')
" 2>/dev/null || echo "Health endpoint unreachable"

Decision Tree

Is Webflow API returning errors?
├── YES
│  

Webflow Install & Auth

Overview

Set up the official Webflow JS SDK (webflow-api on npm) and configure authentication

using either a workspace/site API token or OAuth 2.0 for Data Client Apps.

Prerequisites

• Node.js 18+
• npm, pnpm, or yarn
• A Webflow account with a workspace
• An API token (workspace or site) from https://developers.webflow.com

Instructions

Step 1: Install the SDK

# npm
npm install webflow-api

# pnpm
pnpm add webflow-api

# yarn
yarn add webflow-api

The package is webflow-api (not @webflow/sdk). Current version: 3.x (Data API v2).

Step 2: Choose Authentication Method

Webflow offers two auth methods:

Step 3: Token-Based Authentication

# Set environment variable (never hardcode tokens)
echo 'WEBFLOW_API_TOKEN=your-token-here' >> .env
echo '.env' >> .gitignore

import { WebflowClient } from "webflow-api";

// Initialize with workspace or site token
const webflow = new WebflowClient({
  accessToken: process.env.WEBFLOW_API_TOKEN!,
});

Step 4: OAuth 2.0 Flow (Data Client Apps)

For apps that need user authorization, implement the OAuth 2.0 authorization code flow:

import express from "express";
import { WebflowClient } from "webflow-api";

const app = express();

const CLIENT_ID = process.env.WEBFLOW_CLIENT_ID!;
const CLIENT_SECRET = process.env.WEBFLOW_CLIENT_SECRET!;
const REDIRECT_URI = "https://yourapp.com/auth/webflow/callback";

// Step 1: Redirect user to Webflow authorization page
// Scopes: sites:read, sites:write, cms:read, cms:write,
//         pages:read, pages:write, forms:read, ecommerce:read,
//         ecommerce:write, custom_code:read, custom_code:write
app.get("/auth/webflow", (req, res) => {
  const scopes = "sites:read cms:read cms:write";
  const authUrl =
    `https://webflow.com/oauth/authorize` +
    `?client_id=${CLIENT_ID}` +
    `&response_type=code` +
    `&redirect_uri=${encodeURIComponent(REDIRECT_URI)}` +
    `&scope=${encodeURIComponent(scopes)}`;
  res.redirect(authUrl);
});

// Step 2: Exchange authorization code for access token
// The authorization code expires in 15

Webflow Local Dev Loop

Overview

Set up a fast, reproducible local development workflow for Webflow Data API v2 integrations

with TypeScript, hot reload, vitest mocking, and ngrok webhook tunneling.

Prerequisites

• Completed webflow-install-auth setup
• Node.js 18+ with npm/pnpm
• API token with required scopes
• ngrok (optional, for webhook testing)

Instructions

Step 1: Project Structure

my-webflow-project/
├── src/
│   ├── webflow/
│   │   ├── client.ts          # WebflowClient singleton
│   │   ├── collections.ts    # CMS collection operations
│   │   ├── sites.ts           # Site operations
│   │   └── types.ts           # Shared types
│   ├── webhooks/
│   │   └── handler.ts         # Webhook endpoint
│   └── index.ts
├── tests/
│   ├── collections.test.ts
│   └── fixtures/
│       └── mock-items.json
├── .env.local                 # Local secrets (git-ignored)
├── .env.example               # Template for team
├── tsconfig.json
├── vitest.config.ts
└── package.json

Step 2: Package Configuration

{
  "name": "my-webflow-project",
  "type": "module",
  "scripts": {
    "dev": "tsx watch src/index.ts",
    "build": "tsc",
    "test": "vitest run",
    "test:watch": "vitest --watch",
    "tunnel": "ngrok http 3000"
  },
  "dependencies": {
    "webflow-api": "^3.3.0",
    "express": "^4.21.0"
  },
  "devDependencies": {
    "tsx": "^4.19.0",
    "typescript": "^5.6.0",
    "vitest": "^2.1.0",
    "@types/express": "^5.0.0",
    "@types/node": "^22.0.0"
  }
}

Step 3: Environment Setup

# .env.example
WEBFLOW_API_TOKEN=your-token-here
WEBFLOW_SITE_ID=your-site-id
WEBFLOW_WEBHOOK_SECRET=your-webhook-secret
NODE_ENV=development

cp .env.example .env.local
# Edit .env.local with real values

Load environment in your app:

// src/webflow/client.ts
import { WebflowClient } from "webflow-api";
import { config } from "dotenv";

config({ path: ".env.local" });

let client: WebflowClient | null = null;

export function getWebflowClient(): WebflowClient {
  if (!client) {
    const token = process.env.WEBFLOW_API_TOKEN;
    if (!token) throw new Error("WEBFLOW_API_TOKEN not set in .env.local");

    client = new WebflowClient({
      accessToken: token,
    });
  }
  return client;
}

export function getSiteId(): string {
  const siteId = process.env.WEBFLOW_SITE_ID;
  if (!siteId) throw new Error(&

Webflow Migration Deep Dive

Overview

Comprehensive guide for migrating content to Webflow CMS via the Data API v2.

Covers assessment, data mapping, bulk import (100 items/batch), validation,

and rollback. Handles WordPress, Contentful, Strapi, CSV, and JSON source formats.

Prerequisites

• webflow-api SDK installed
• API token with cms:read and cms:write scopes
• Target Webflow site with CMS collections created in the Designer
• Source data exported (JSON, CSV, or API access)

Migration Types

Instructions

Step 1: Assess Target Collection Schema

Before importing, understand exactly what fields the target collection expects:

import { WebflowClient } from "webflow-api";

const webflow = new WebflowClient({
  accessToken: process.env.WEBFLOW_API_TOKEN!,
});

async function assessTarget(siteId: string) {
  const { collections } = await webflow.collections.list(siteId);

  const schema: Record<string, any> = {};

  for (const col of collections!) {
    schema[col.slug!] = {
      id: col.id,
      displayName: col.displayName,
      itemCount: col.itemCount,
      fields: col.fields?.map(f => ({
        slug: f.slug,
        displayName: f.displayName,
        type: f.type,
        required: f.isRequired,
        // Types: PlainText, RichText, Image, MultiImage, Video,
        //        Link, Email, Phone, Number, DateTime, Switch,
        //        Color, Option, File, Reference, MultiReference
      })),
    };
  }

  console.log(JSON.stringify(schema, null, 2));
  return schema;
}

Step 2: Build Data Transformer

Map source data format to Webflow's fieldData structure:

interface SourcePost {
  title: string;
  content: string;      // HTML content
  excerpt: string;
  author: string;
  date: string;          // ISO 8601
  categories: string[];
  featured_image?: string;
  status: "published" | "draft";
}

interface WebflowFieldData {
  name: string;          // Required system field
  slug: string;          // Required system field
  [key: string]: any;    // Custom fields use slug format
}

function transformPost(source: SourcePost): {
  fieldData: WebflowFieldData;
  isDraft: boolean;
} {

Webflow Multi-Environment Setup

Overview

Configure Webflow Data API v2 integrations across development, staging, and production

with separate API tokens, site IDs, and secret management. Each environment targets

a different Webflow site for complete isolation.

Prerequisites

• Separate Webflow sites for each environment (or at minimum, separate API tokens)
• Secret management solution (Vault, AWS Secrets Manager, or GCP Secret Manager)
• CI/CD pipeline with environment variable support

Environment Strategy

Instructions

Step 1: Environment Configuration

// src/config/webflow.ts
type Environment = "development" | "staging" | "production";

interface WebflowEnvConfig {
  accessToken: string;
  siteId: string;
  maxRetries: number;
  webhookSecret: string;
  debug: boolean;
}

function detectEnvironment(): Environment {
  const env = process.env.NODE_ENV || "development";
  const valid: Environment[] = ["development", "staging", "production"];
  return valid.includes(env as Environment) ? (env as Environment) : "development";
}

export function getWebflowConfig(): WebflowEnvConfig {
  const env = detectEnvironment();

  // Each environment has its own token and site
  const configs: Record<Environment, () => WebflowEnvConfig> = {
    development: () => ({
      accessToken: requireEnv("WEBFLOW_API_TOKEN"),
      siteId: requireEnv("WEBFLOW_SITE_ID"),
      maxRetries: 1,
      webhookSecret: process.env.WEBFLOW_WEBHOOK_SECRET || "",
      debug: true,
    }),
    staging: () => ({
      accessToken: requireEnv("WEBFLOW_API_TOKEN_STAGING"),
      siteId: requireEnv("WEBFLOW_SITE_ID_STAGING"),
      maxRetries: 2,
      webhookSecret: requireEnv("WEBFLOW_WEBHOOK_SECRET_STAGING"),
      debug: false,
    }),
    production: () => ({
      accessToken: requireEnv("WEBFLOW_API_TOKEN_PROD"),
      siteId: requireEnv("WEBFLOW_SITE_ID_PROD"),
      maxRetries: 3,
      webhookSecret: requireEnv("WEBFLOW_WEBHOOK_SECRET_PROD"),
      debug: false,
    }),
  };

  const config = configs[env]();
  console.log(`[webflow] Environment: ${env}, Site: ${config.siteId.substring(0, 8)}...`);
  return config;
}

function requireEnv(name:

Webflow Observability

Overview

Full observability stack for Webflow Data API v2 integrations: Prometheus metrics

for API call counting and latency, OpenTelemetry distributed tracing, structured

JSON logging, and alerting rules for error rate and rate limit exhaustion.

Prerequisites

• prom-client for Prometheus metrics
• @opentelemetry/api for tracing (optional)
• pino for structured logging
• Prometheus + Grafana (or compatible backend)

Instructions

Step 1: Prometheus Metrics

// src/observability/metrics.ts
import { Registry, Counter, Histogram, Gauge } from "prom-client";

export const registry = new Registry();

// API request counter (by operation and status)
export const apiRequests = new Counter({
  name: "webflow_api_requests_total",
  help: "Total Webflow API requests",
  labelNames: ["operation", "status_code", "method"] as const,
  registers: [registry],
});

// Request duration histogram
export const apiDuration = new Histogram({
  name: "webflow_api_request_duration_seconds",
  help: "Webflow API request duration in seconds",
  labelNames: ["operation"] as const,
  buckets: [0.05, 0.1, 0.25, 0.5, 1, 2, 5, 10],
  registers: [registry],
});

// Error counter by type
export const apiErrors = new Counter({
  name: "webflow_api_errors_total",
  help: "Webflow API errors by status code",
  labelNames: ["operation", "status_code", "error_type"] as const,
  registers: [registry],
});

// Rate limit remaining gauge
export const rateLimitRemaining = new Gauge({
  name: "webflow_rate_limit_remaining",
  help: "Remaining API calls before rate limit",
  registers: [registry],
});

// CMS items gauge (track total items across collections)
export const cmsItemCount = new Gauge({
  name: "webflow_cms_items_total",
  help: "Total CMS items by collection",
  labelNames: ["collection", "site"] as const,
  registers: [registry],
});

// Webhook event counter
export const webhookEvents = new Counter({
  name: "webflow_webhook_events_total",
  help: "Received webhook events by trigger type",
  labelNames: ["trigger_type", "status"] as const,
  registers: [registry],
});

Step 2: Instrumented Client Wrapper

// src/observability/instrumented-client.ts
import { WebflowClient } from "webflow-api";
import { apiRequests, apiDuration, apiErrors, rateLimitRemaining } from "./metrics.js";

export async function instrumentedCall<T>(
  operation: string,
  method: string,
  fn: () => Promise<T>
): Promise<T> {
  const timer = apiDuration.startTimer({ operation 

Webflow Performance Tuning

Overview

Optimize Webflow Data API v2 performance. Key insight: **CDN-cached requests

to live items have no rate limits** — use the Content Delivery API for read-heavy

workloads and reserve write API calls for mutations.

Prerequisites

• webflow-api SDK installed
• Understanding of your read/write ratio
• Redis or in-memory cache (optional)

Webflow Performance Characteristics

Key optimization: CDN-cached live item reads do not count against rate limits.

Instructions

Strategy 1: Use Content Delivery API for Reads

// For published content that visitors see, use live item endpoints.
// These are served by Webflow's CDN and have no rate limits.

async function getPublishedContent(collectionId: string) {
  // CDN-cached — fast, no rate limit
  const { items } = await webflow.collections.items.listItemsLive(collectionId, {
    limit: 100,
  });
  return items;
}

// Single live item — also CDN-cached
async function getPublishedItem(collectionId: string, itemId: string) {
  return webflow.collections.items.getItemLive(collectionId, itemId);
}

Strategy 2: Application-Level Response Caching

import { LRUCache } from "lru-cache";

const cache = new LRUCache<string, any>({
  max: 500,              // Max entries
  ttl: 5 * 60 * 1000,   // 5-minute TTL
  updateAgeOnGet: true,  // Reset TTL on access
});

async function cachedFetch<T>(
  key: string,
  fetcher: () => Promise<T>,
  ttlMs?: number
): Promise<T> {
  const cached = cache.get(key);
  if (cached !== undefined) return cached as T;

  const result = await fetcher();
  cache.set(key, result, { ttl: ttlMs });
  return result;
}

// Usage — cache collection schema (changes rarely)
const collections = await cachedFetch(
  `collections:${siteId}`,
  () => webflow.collections.list(siteId).then(r => r.collections),
  30 * 60 * 1000 // 30-minute cache for schemas
);

// Cache live items (shorter TTL for dynamic content)
const items = await cachedFetch(
  `items:live:${collectionId}`,
  () => webflow.collections.items.listItemsLive(collectionId).the

Webflow Production Checklist

Overview

Complete pre-deployment checklist for Webflow Data API v2 integrations, covering

authentication, error handling, rate limits, monitoring, and rollback.

Prerequisites

• Staging environment tested and verified
• Production API token with minimal scopes
• Deployment pipeline configured
• Monitoring/alerting infrastructure ready

Instructions

Pre-Deployment Configuration

• [ ] Production API token in secure vault (not .env file on server)
• [ ] Minimal scopes — only scopes the integration actually uses
• [ ] Site token used where workspace token is not needed
• [ ] Environment variables set in deployment platform (Vercel/Fly/Cloud Run)
• [ ] Webhook secrets stored securely, not hardcoded
• [ ] No tokens in client-side code — all API calls server-side only

Code Quality Verification

• [ ] All tests passing — unit tests with mocked SDK, integration tests with test token
• [ ] No hardcoded credentials — grep -r "Bearer " src/ returns nothing
• [ ] Error handling covers 400, 401, 403, 404, 409, 429, 500
• [ ] Rate limit handling — SDK maxRetries configured, bulk endpoints used
• [ ] Pagination — all list operations handle offset/limit correctly
• [ ] Logging is production-appropriate (no PII, structured JSON)
• [ ] Webhook signatures verified — verifyWebhookSignature() on every webhook

Rate Limit Readiness

• [ ] Bulk endpoints used for multi-item operations (100 items/request max)
• [ ] Request queue with concurrency control (p-queue or similar)
• [ ] Site publish rate limited to max 1 per minute
• [ ] Retry-After header honored in custom retry logic
• [ ] SDK maxRetries set (default: 2, increase for critical paths)

Health Check Endpoint

// api/health.ts
import { WebflowClient } from "webflow-api";

export async function GET() {
  const webflow = new WebflowClient({
    accessToken: process.env.WEBFLOW_API_TOKEN!,
  });

  const checks: Record<string, any> = {};
  const start = Date.now();

  try {
    const { sites } = await webflow.sites.list();
    checks.webflow = {
      status: "connected",
      sites: sites?.length || 0,
      latencyMs: Date.now() - start,
    };
  } catch (error: any) {
    checks.webflow = {
      status: "disconnected",
      error: error.statusCode || error.message,
      laten

Webflow Rate Limits

Overview

Handle Webflow Data API v2 rate limits using the SDK's built-in retry, manual

backoff strategies, request queuing, and bulk endpoints to maximize throughput

without hitting 429 errors.

Prerequisites

• webflow-api SDK installed
• Understanding of async/await patterns
• Knowledge of your site plan's rate limits

Webflow Rate Limit Rules

Per-Key Rate Limits

Rate limits are applied per API key (not per site or per user). Each token

has its own independent rate limit counter.

Rate Limit Response Headers

429 Response

{
  "code": "rate_limit",
  "message": "Rate limit exceeded. Please retry after 60 seconds."
}

Instructions

Step 1: SDK Built-In Retry

The webflow-api SDK automatically retries 429 and 5xx errors with exponential backoff:

import { WebflowClient } from "webflow-api";

const webflow = new WebflowClient({
  accessToken: process.env.WEBFLOW_API_TOKEN!,
  maxRetries: 3, // Default: 2. SDK uses exponential backoff.
});

// The SDK handles 429s transparently — no extra code needed
const { sites } = await webflow.sites.list();

Step 2: Manual Exponential Backoff with Jitter

For operations outside the SDK or when you need custom retry logic:

async function withBackoff<T>(
  operation: () => Promise<T>,
  config = {
    maxRetries: 5,
    baseDelayMs: 1000,
    maxDelayMs: 60000,
    jitterMs: 500,
  }
): Promise<T> {
  for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
    try {
      return await operation();
    } catch (error: any) {
      const status = error.statusCode || error.status;

      // Only retry on 429 (rate limit) and 5xx (server errors)
     

Webflow Reference Architecture

Overview

Production-ready architecture for Webflow Data API v2 integrations. Layered design

separating API access, business logic, caching, and webhook handling.

Prerequisites

• TypeScript 5+ project
• webflow-api SDK (v3.x)
• Understanding of service-oriented architecture
• Redis (optional, for distributed caching)

Project Structure

my-webflow-project/
├── src/
│   ├── webflow/                     # Webflow API layer
│   │   ├── client.ts                # WebflowClient singleton
│   │   ├── types.ts                 # TypeScript types for Webflow resources
│   │   ├── errors.ts                # Custom error classes
│   │   └── cache.ts                 # Response caching (LRU/Redis)
│   ├── services/                    # Business logic layer
│   │   ├── cms.service.ts           # CMS content management
│   │   ├── ecommerce.service.ts     # Products, orders, inventory
│   │   ├── forms.service.ts         # Form submission processing
│   │   └── sync.service.ts          # External data sync
│   ├── webhooks/                    # Event handling layer
│   │   ├── router.ts                # Event type routing
│   │   ├── handlers/
│   │   │   ├── form-submission.ts
│   │   │   ├── cms-item-changed.ts
│   │   │   └── ecomm-new-order.ts
│   │   └── middleware.ts            # Signature verification
│   ├── api/                         # HTTP endpoints
│   │   ├── health.ts
│   │   ├── webhooks.ts
│   │   └── content.ts
│   └── config/
│       └── webflow.ts               # Environment-aware config
├── tests/
│   ├── unit/
│   │   ├── services/
│   │   └── webhooks/
│   └── integration/
│       └── webflow.integration.test.ts
├── .env.example
├── tsconfig.json
└── package.json

Layer Architecture

┌──────────────────────────────────────────────────┐
│                  API Layer                        │
│   Express routes, webhook endpoints, health      │
├──────────────────────────────────────────────────┤
│               Service Layer                       │
│   CMS sync, ecommerce, form processing           │
│   (Business logic, orchestration)                 │
├──────────────────────────────────────────────────┤
│             Webflow Client Layer                  │
│   WebflowClient wrapper, error handling, types    │
├──────────────────────────────────────────────────┤
│           Infrastructure Layer                    │
│   Cache (LRU/Redis), queue (p-queue), monitoring  │
└──────────────────────────────────────────────────┘

Instructions

Layer 1: Webflow Client

// src/webflow/client.ts
import { WebflowClient } from "webflow-api";
import { getConfig } from "../config/webflow.js";

let client: WebflowClient | null = null;

export function getClient(): WebflowClient {
  if (!client) {
    co

Webflow SDK Patterns

Overview

Production-ready patterns for the webflow-api SDK (v3.x). Covers singleton client,

typed error handling, pagination, raw response headers, and multi-tenant factory.

Prerequisites

• webflow-api v3.x installed
• TypeScript 5+ project
• Familiarity with async/await and the Webflow Data API v2

Instructions

Pattern 1: Singleton Client with Configuration

// src/webflow/client.ts
import { WebflowClient } from "webflow-api";

interface WebflowConfig {
  accessToken: string;
  timeout?: number;   // Request timeout in ms (default: SDK default)
  maxRetries?: number; // Auto-retry on 429/5xx (default: 2)
}

let instance: WebflowClient | null = null;

export function getWebflowClient(config?: Partial<WebflowConfig>): WebflowClient {
  if (!instance) {
    const token = config?.accessToken || process.env.WEBFLOW_API_TOKEN;
    if (!token) throw new Error("WEBFLOW_API_TOKEN required");

    instance = new WebflowClient({
      accessToken: token,
      // The SDK supports timeout and maxRetries natively
      ...(config?.timeout && { timeout: config.timeout }),
      ...(config?.maxRetries !== undefined && { maxRetries: config.maxRetries }),
    });
  }
  return instance;
}

// Reset client (useful for token rotation)
export function resetWebflowClient(): void {
  instance = null;
}

Pattern 2: Typed Error Handling

The SDK throws WebflowError subclasses. Handle them by type:

import { WebflowClient } from "webflow-api";

// SDK errors are subclasses of WebflowError
// Common HTTP status codes: 400, 401, 403, 404, 409, 429, 500

async function safeWebflowCall<T>(
  operation: () => Promise<T>,
  context: string
): Promise<{ data: T | null; error: string | null }> {
  try {
    const data = await operation();
    return { data, error: null };
  } catch (err: any) {
    const statusCode = err.statusCode || err.status;
    const message = err.message || String(err);

    // Log with context for debugging
    console.error(`[Webflow] ${context} failed:`, {
      status: statusCode,
      message,
      body: err.body,
    });

    // Classify the error
    switch (statusCode) {
      case 401:
        console.error("Token invalid or revoked. Rotate token.");
        break;
      case 403:
        console.error("Missing required scope. Check token scopes.");
        break;
      case 404:
        console.error("Resource not found. Verify IDs.");
        break;
      case 409:
        console.error("Conflict — item may already exist with this slug.");
        break;
      case 429:
        console.error("Rate limited. SDK will auto-retry with backoff.");
        break;
      default:
        

Webflow Security Basics

Overview

Security best practices for Webflow Data API v2 tokens, OAuth secrets, webhook

verification, and access control. Covers the full lifecycle from token creation

to rotation and revocation.

Prerequisites

• Webflow developer account at developers.webflow.com
• Understanding of environment variables
• Secret management solution (vault, cloud secret manager, etc.)

Instructions

Step 1: Token Types and Selection

Rule: Never use a workspace token where a site token would suffice.

Step 2: Least Privilege Scopes

Only request scopes your integration actually needs:

// Example: Read-only integration needs only these scopes
const READ_ONLY_SCOPES = "sites:read cms:read pages:read forms:read";

// CMS sync integration
const CMS_SYNC_SCOPES = "sites:read cms:read cms:write";

// Full ecommerce integration
const ECOMMERCE_SCOPES = "sites:read ecommerce:read ecommerce:write";

Step 3: Secure Token Storage

# .gitignore — MANDATORY
.env
.env.local
.env.*.local
*.pem
*.key

# .env.local (never committed)
WEBFLOW_API_TOKEN=your-token-here
WEBFLOW_WEBHOOK_SECRET=your-webhook-secret
WEBFLOW_OAUTH_CLIENT_SECRET=your-oauth-secret

// Load from environment, never hardcode
import { WebflowClient } from "webflow-api";

function createClient(): WebflowClient {
  const token = process.env.WEBFLOW_API_TOKEN;
  if (!token) {
    throw new Error(
      "WEBFLOW_API_TOKEN not set. " +
      "Generate at https://developers.webflow.com"
    );
  }
  return new WebflowClient({ accessToke

Webflow Upgrade & Migration

Overview

Guide for upgrading the webflow-api SDK and migrating from Webflow Data API v1

to v2. Covers breaking changes, endpoint mapping, import updates, and rollback.

Prerequisites

• Current webflow-api SDK installed
• Git for version control (create upgrade branch)
• Test suite available
• Staging environment for validation

Instructions

Step 1: Assess Current Version

# Check installed version
npm list webflow-api

# Check latest available
npm view webflow-api version

# View changelog
npm view webflow-api --json | jq '.versions[-5:]'

Step 2: SDK Version History

v1 endpoints deprecation: late 2026. Migrate before then.

Step 3: API v1 to v2 Migration Map

Base URL Change

v1: https://api.webflow.com
v2: https://api.webflow.com/v2

Authentication Change

// v1 (old) — API key
import Webflow from "webflow-api";
const webflow = new Webflow({ token: "your-api-key" });

// v2 (current) — Access token
import { WebflowClient } from "webflow-api";
const webflow = new WebflowClient({ accessToken: "your-access-token" });

Endpoint Migration Map

import { WebflowClient } from "webflow-api";

const webflow = new WebflowClient({
  accessToken: process.env.WEBFLOW_API_TOKEN!,
});

const siteId = process.env.WEBFLOW_SITE_ID!;
const webhookUrl = "https://your-app.com/webhooks/webflow";

async function registerWebhooks() {
  const triggerTypes = [