The decision that determines everything downstream — and why most developers pick the wrong one first.

You’ve decided to build on Whop. You open the developer docs and immediately hit a fork in the road: App, SaaS, or License Keys.

The docs explain how each one works. What they don’t tell you is which one to choose — and picking the wrong path means rebuilding from scratch when you realize your integration doesn’t fit the use case.

This post makes that decision clear before you write a line of code.

The Three Integration Paths — What They Actually Are

Path 1: Whop App

A Whop App is a Next.js application that runs inside the Whop platform via iFrame. Your customers don’t leave Whop — they interact with your app directly inside their dashboard.

Whop handles:

• Authentication (users are already logged into Whop)
• Payment and membership gating
• App distribution via the Whop App Store
• Hosting discovery and installation

You handle:

• Your app’s actual functionality
• Your own database and backend
• The UI that renders inside the iFrame

The install experience: A seller adds your app to their Whop. Their members see it inside their dashboard. No external login, no separate URL to remember, no onboarding friction.

import { WhopServerSdk } from "@whop/api";

export const whopSdk = WhopServerSdk({
  appId: process.env.NEXT_PUBLIC_WHOP_APP_ID!,
  appApiKey: process.env.WHOP_API_KEY!,
});

// Check if the current user has access
const hasAccess = await whopSdk.access.checkIfUserHasAccessToAccessPass({
  userId: user.whop_user_id,
  accessPassId: process.env.WHOP_ACCESS_PASS_ID!,
});

Path 2: SaaS Integration

A SaaS integration means you have an existing product with its own URL — your own login, your own database, your own UI. You’re using Whop purely as a payment and membership layer, not as a hosting environment.

Whop handles:

• Checkout and payment processing
• Membership creation and renewal
• Webhook events when memberships change status

You handle:

• Everything else — authentication, product, database, UI

The user experience: Customer pays on Whop → Whop fires a webhook to your server → your server provisions access → customer logs into your product normally.

// Your webhook handler — provisioning access on membership.went_valid
app.post('/webhooks/whop', express.raw({ type: 'application/json' }), async (req, res) => {
  const event = JSON.parse(req.body.toString());

  if (event.action === 'membership.went_valid') {
    const { user, plan } = event.data;

    // Provision access in your own database
    await db.users.upsert({
      whop_user_id: user.id,
      email: user.email,
      plan_id: plan.id,
      status: 'active',
    });
  }

  if (event.action === 'membership.went_invalid') {
    // Revoke access
    await db.users.update({
      where: { whop_user_id: event.data.user.id },
      data: { status: 'inactive' }
    });
  }

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

Path 3: License Keys

License key validation is for software that runs on a user’s machine — desktop apps, CLI tools, scripts, browser extensions, game mods. The user enters a key into your software; your software validates it against Whop’s API.

Whop handles:

• Key generation and assignment on purchase
• Key validation API
• Metadata binding (tie a key to a specific machine or user)

You handle:

• The software itself
• Calling Whop’s validation API on launch or periodically

import requests

def validate_license(license_key: str, machine_id: str) -> bool:
    response = requests.post(
        "https://api.whop.com/v2/memberships/validate_license",
        headers={"Authorization": f"Bearer {YOUR_API_KEY}"},
        json={
            "license_key": license_key,
            "metadata": {"machine_id": machine_id}
        }
    )

    # 201 = valid (first use or matching metadata)
    # 400 = invalid (metadata mismatch — different machine)
    return response.status_code == 201

The Decision Framework — Which Path Is Right for You?

Answer these three questions:

1. Does your product run inside a browser, or on a user’s machine?

• Browser-based → App or SaaS
• Desktop / CLI / script → License Keys

2. Do you already have an existing product with its own login system?

• Yes, with its own URL and auth → SaaS integration
• No, building fresh → Whop App (let Whop handle auth and hosting)

3. Do you want your product to appear inside Whop’s ecosystem, or stand alone?

• Inside Whop (marketplace discovery, iFrame integration) → Whop App
• Standalone product using Whop only for payments → SaaS

Here’s the decision matrix:

The Mistake Most Developers Make

The most common wrong turn: building a SaaS integration when you should have built a Whop App.

Here’s how it happens: You have an idea. You build a Next.js app. You think “I’ll use Whop for payments and handle auth myself.” You implement OAuth, build a login page, set up sessions, handle token refresh.

Then you discover that Whop Apps handle all of that for you — and your app would have been in front of Whop’s entire user base through the App Store instead of requiring your own marketing to drive traffic.

The SaaS path makes sense when you have an existing product with real users who are already logged in. For net-new builds, Whop Apps are almost always the right starting point.

The Webhook Routing Problem (All Three Paths Hit This)

Whop sends all events to a single webhook endpoint. If you’re handling multiple event types — membership valid, membership invalid, payment succeeded, payment refunded — you need a clean router.

Here’s the pattern that works:

const handlers: Record<string, (data: any) => Promise<void>> = {
  'membership.went_valid':   handleMembershipValid,
  'membership.went_invalid': handleMembershipInvalid,
  'payment.succeeded':       handlePaymentSucceeded,
  'payment.refunded':        handlePaymentRefunded,
};

app.post('/webhooks/whop', async (req, res) => {
  const { action, data } = req.body;

  // Respond immediately — process async
  res.json({ received: true });

  const handler = handlers[action];
  if (handler) {
    await handler(data).catch(err => {
      console.error(`Handler failed for ${action}:`, err);
    });
  } else {
    console.log(`Unhandled webhook action: ${action}`);
  }
});

Respond immediately to avoid timeouts. Route by action. Handle errors per-handler so one failure doesn’t break the rest.

The License Key Metadata Gotcha

If you’re on the License Key path, there’s one behavior that trips up almost everyone: the 201 vs 400 response.

• 201 — The key is valid. Either: (a) metadata is empty (first use), or (b) the metadata you sent matches what’s already stored.
• 400 — The key is invalid. The metadata you sent doesn’t match what’s stored (different machine, different user).

This means a key that returns 201 on a user’s laptop will return 400 when they try to use it on their desktop. This is intentional — it’s machine-binding. But if you’re not expecting it, it looks like the key stopped working.

The fix when a user legitimately switches machines:

# Reset the license key metadata (clears machine binding)
requests.post(
    f"https://api.whop.com/v2/memberships/{membership_id}",
    headers={"Authorization": f"Bearer {YOUR_API_KEY}"},
    json={"metadata": {}}  # Empty body resets the binding
)

Users can also reset their own key via their Whop account at whop.com/@me/settings/memberships/.

Which SDK to Use

Whop has three official SDKs:

# TypeScript / JavaScript (recommended for Next.js apps)
npm install @whop/sdk

# Python
pip install whop-sdk

# Ruby
gem install whop_sdk

All three are generated with Stainless, which means they’re type-safe, handle pagination automatically, and retry on rate limits and transient errors by default. The TypeScript SDK is the most complete and most actively maintained — use it if you have a choice.

For Whop Apps specifically, use @whop/sdk with WhopServerSdk for server-side calls and the Whop iframe helpers for client-side communication.

Where to Start

Building a new product from scratch → Start with the Whop App quickstart. Clone the whop-saas-starter template and get to a working iFrame integration in under 30 minutes.

Integrating an existing SaaS → Start with webhooks. Get membership.went_valid and membership.went_invalid working first — those two events handle 90% of your provisioning logic.

Building desktop software → Start with license key validation. Get the 201/400 behavior working in your dev environment before you integrate it into your software.

In all three cases, the right first step is the same: get your API key from the Whop developer dashboard, make one successful API call, and validate that your credentials work before building anything else.

If you’re building on Whop and the integration path still isn’t clear — drop a comment. I’ll help you figure out which one fits your use case.

Disclosure: This post was produced by AXIOM, an agentic developer advocacy workflow powered by Anthropic’s Claude, operated by Jordan Sterchele. Human-reviewed before publication.