> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sequenzy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Whop Integration

> Sync revenue data from Whop to power segments and automations

Connect your Whop account to automatically sync revenue metrics for all your subscribers. This enables powerful segmentation based on MRR and LTV.

## What is Whop?

[Whop](https://whop.com) is a marketplace and commerce platform for selling access to communities, software, courses, and other digital products. Creators list memberships and products on Whop, and Whop handles checkout, billing, and access management for their customers.

## Connecting Whop

Whop requires manual API key and webhook setup. Connecting happens in two steps in Sequenzy: first you provide your Company ID and API key, then you set up a webhook and provide its signing secret.

### Step 1: Find Your Whop Company ID

1. Go to your [Whop Dashboard](https://whop.com/dashboard)
2. Your **Company ID** is visible in the dashboard URL (format: `biz_xxxxxxxxx`)
3. Copy this ID for later

### Step 2: Create a Whop API Key

1. In the Whop Dashboard, go to the **Developer** tab
2. Open **Account API Keys**
3. Click **Create**
4. Copy the API key

<Warning>
  Your API key must include the `member:basic:read`, `member:email:read`,
  `payment:basic:read`, `plan:basic:read`, `access_pass:basic:read`,
  `member:phone:read`, `promo_code:basic:read`, `payment:dispute:read`, and
  `payment:resolution_center_case:read` permissions. Whop requires this complete
  permission set for payment history and authoritative refund totals. Without
  `member:email:read`, Whop omits customer emails and Sequenzy cannot match
  payments to your subscribers. Make sure all nine permissions are enabled
  before creating the key.
</Warning>

### Step 3: Enter Your Company ID and API Key in Sequenzy

1. Go to **Settings → Integrations** in Sequenzy
2. Click **Connect** next to Whop
3. Enter your:
   * **Company ID** (from Step 1)
   * **API Key** (from Step 2)
4. Continue to the next step

### Step 4: Set Up Webhooks in Whop

1. In the Whop Dashboard, go to the **Developer** tab
2. Click **Create Webhook**
3. Enter your Sequenzy webhook URL:
   ```
   https://api.sequenzy.com/api/webhooks/whop/{your-sequenzy-company-id}
   ```
   <Note>
     This path uses your Sequenzy company ID, not the Whop `biz_...` Company ID
     from Step 1. The connect modal shows the correct URL already filled in,
     with a copy button, so copy it from there instead of building it by hand.
   </Note>
4. Select these events to listen for:
   * `payment.succeeded`
   * `payment.failed`
   * `membership.activated`
   * `membership.deactivated`
   * `refund.created`
   * `refund.updated`
5. Click **Create** to save the webhook
6. Copy the **Webhook Secret** (format: `whsec_xxxxxxxxx`) shown at creation

### Step 5: Add the Webhook Secret in Sequenzy

1. Back in the Sequenzy connect modal, paste the **Webhook Secret** (from Step 4)
2. Click **Connect Whop**

Sequenzy will immediately begin receiving webhook events from Whop and start a historical sync of your existing customers.

## Synced Attributes

When connected, Sequenzy adds these attributes to each subscriber matched by email:

| Attribute        | Type   | Description                                                                 |
| ---------------- | ------ | --------------------------------------------------------------------------- |
| `mrr`            | Number | Monthly Recurring Revenue in dollars (normalized from any billing interval) |
| `ltv`            | Number | Lifetime Value - total payments minus refunds                               |
| `whopCustomerId` | String | The subscriber's customer ID in Whop                                        |

### MRR Calculation

MRR is calculated from active, trialing, and `past_due` memberships on renewal
plans:

* **Monthly plans**: Used as-is
* **Yearly plans**: Divided by 12
* All amounts are converted to USD

Whop keeps `past_due` memberships eligible for payment retries, so Sequenzy
continues counting their MRR and customer/interval tags until Whop ends access.
One-time plans and completed one-time memberships contribute to LTV, not MRR.

If a plan uses a currency for which Sequenzy has no reliable USD exchange rate,
that membership's MRR is skipped without blocking the rest of the historical
sync. LTV still uses Whop's USD valuation when Whop supplies one.

## Tracked Events

When you connect Whop, these events are automatically tracked for use in automations:

| Event                   | Triggered When                      |
| ----------------------- | ----------------------------------- |
| `saas.purchase`         | Payment succeeded                   |
| `saas.purchase_monthly` | Recurring payment on a monthly plan |
| `saas.purchase_yearly`  | Recurring payment on a yearly plan  |
| `saas.payment_failed`   | Payment failed                      |
| `saas.cancelled`        | Membership cancelled                |
| `saas.churn`            | Membership expired or deactivated   |
| `saas.refund`           | Refund succeeded                    |

## Historical Sync

Connecting Whop triggers an automatic backfill of your existing Whop customers and memberships, so your subscribers' `mrr`, `ltv`, and `whopCustomerId` attributes are populated right away rather than only updating as new events arrive.

To re-sync at any time:

1. Go to **Settings → Integrations**
2. Find your connected Whop account
3. Click **Sync Revenue**

## Using Revenue Data

### Building Segments

With MRR and LTV synced as numeric attributes, you can create sophisticated segments:

**Revenue-based segments:**

* `mrr >= 100` - High MRR customers
* `ltv > 1000` - Lifetime high-value customers
* `mrr >= 50 AND mrr < 200` - Mid-tier customers

**Combining with events:**

* Subscribers with a recent `saas.churn` event and high `ltv` - win-back targets
* Subscribers with a recent `saas.cancelled` event and high `mrr` - at-risk high-value customers

### Automations

Trigger automations when revenue events or attributes change:

* Send a thank-you email on `saas.purchase`
* Trigger a win-back sequence when a subscriber gets a `saas.churn` event
* Notify your team when a high-value customer cancels

## How Matching Works

Subscribers are matched by email address (case-insensitive). A Whop customer with email `User@Example.com` will match a subscriber with email `user@example.com`.

If a Whop customer doesn't have an email in the webhook or doesn't match any subscriber, the event is acknowledged but no action is taken.

## Troubleshooting

### Customer Emails Missing

If events are being acknowledged but subscribers aren't being updated:

1. Confirm your API key has the `member:basic:read`, `member:email:read`, `payment:basic:read`, `plan:basic:read`, `access_pass:basic:read`, `member:phone:read`, `promo_code:basic:read`, `payment:dispute:read`, and `payment:resolution_center_case:read` permissions enabled in Whop's Developer tab
2. If a permission was missing when you first connected, create a new API key with all nine permissions, disconnect Whop in Sequenzy, and reconnect it with the new key
3. Check that customers have valid email addresses in Whop

### Webhooks Not Arriving

1. Verify your webhook URL is correct in Whop and includes your Sequenzy company ID
2. Confirm the webhook is enabled and subscribed to `payment.succeeded`, `payment.failed`, `membership.activated`, `membership.deactivated`, `refund.created`, and `refund.updated`
3. Check Whop's webhook logs for failed delivery attempts

### Invalid Webhook Signature

If webhooks are failing with signature errors:

1. Re-copy the `whsec_` secret from Whop's Developer tab, disconnect Whop in Sequenzy, and reconnect it with that secret
2. If you recreated the webhook in Whop, a new secret is generated - reconnect Sequenzy with the latest one
3. Ensure you copied the complete secret, with no extra whitespace