Webflow Prod Checklist

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,
      latencyMs: Date.now() - start,
    };
  }

  const healthy = checks.webflow.status === "connected";

  return Response.json(
    {
      status: healthy ? "healthy" : "degraded",
      services: checks,
      timestamp: new Date().toISOString(),
    },
    { status: healthy ? 200 : 503 }
  );
}

Circuit Breaker Pattern

class WebflowCircuitBreaker {
  private failures = 0;
  private lastFailure = 0;
  private state: "closed" | "open" | "half-open" = "closed";

  constructor(
    private threshold = 5,      // failures before opening
    private resetTimeMs = 60000  // time before trying again
  ) {}

  async execute<T>(operation: () => Promise<T>): Promise<T> {
    if (this.state === "open") {
      if (Date.now() - this.lastFailure > this.resetTimeMs) {
        this.state = "half-open";
      } else {
        throw new Error("Circuit breaker is open — Webflow API unavailable");
      }
    }

    try {
      const result = await operation();
      this.onSuccess();
      return result;
    } catch (error: any) {
      this.onFailure();
      throw error;
    }
  }

  private onSuccess() {
    this.failures = 0;
    this.state = "closed";
  }

  private onFailure() {
    this.failures++;
    this.lastFailure = Date.now();
    if (this.failures >= this.threshold) {
      this.state = "open";
      console.error(`Circuit breaker OPEN after ${this.failures} failures`);
    }
  }
}

const breaker = new WebflowCircuitBreaker();

// Usage
const sites = await breaker.execute(() => webflow.sites.list());

Monitoring Alerts

Graceful Degradation

async function getContentWithFallback(
  collectionId: string,
  cachedData: any[]
): Promise<any[]> {
  try {
    const { items } = await breaker.execute(() =>
      webflow.collections.items.listItemsLive(collectionId)
    );
    // Update cache on success
    await updateCache(collectionId, items);
    return items || [];
  } catch (error) {
    console.warn("Webflow unavailable, serving cached content");
    return cachedData;
  }
}

Pre-Flight Verification Script

#!/bin/bash
echo "=== Webflow Production Pre-Flight ==="

# 1. Token works
HTTP=$(curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $WEBFLOW_API_TOKEN" \
  https://api.webflow.com/v2/sites)
echo "Token valid: $([ "$HTTP" = "200" ] && echo "YES" || echo "NO (HTTP $HTTP)")"

# 2. Webflow platform status
STATUS=$(curl -s https://status.webflow.com/api/v2/status.json | \
  python3 -c "import sys,json; print(json.load(sys.stdin)['status']['description'])" 2>/dev/null)
echo "Webflow status: ${STATUS:-unknown}"

# 3. Rate limit headroom
curl -s -I -H "Authorization: Bearer $WEBFLOW_API_TOKEN" \
  https://api.webflow.com/v2/sites 2>/dev/null | \
  grep -i "x-ratelimit-remaining" || echo "Rate limit headers not available"

# 4. Health endpoint
HEALTH=$(curl -s -o /dev/null -w "%{http_code}" https://your-app.com/api/health)
echo "Health endpoint: HTTP $HEALTH"

Rollback Procedure

# Immediate rollback steps:
# 1. Revert to previous deployment
vercel rollback     # Vercel
fly releases        # Fly.io — find previous release
fly deploy --image registry/app:previous-tag  # Fly.io

# 2. If using feature flags, disable Webflow integration
# 3. Monitor error rates for resolution

Output

• Production-hardened Webflow integration
• Health check endpoint with latency tracking
• Circuit breaker preventing cascade failures
• Monitoring alerts configured
• Rollback procedure documented and tested

Error Handling

Resources

• Webflow Status Page
• Rate Limits
• API Reference

Next Steps

For version upgrades, see webflow-upgrade-migration.