Whop App Integration

Overview

Required Architecture

• Keep Whop API keys only on backend services.
• Route requests as

  app -> backend -> Whop API

  .
• Process Whop webhooks on backend and persist entitlement state locally.
• Reject client-only designs that send

  Authorization: Bearer

  Whop keys from app code.

Workflow

1. Define entitlement policy before coding

• Choose plan model: subscription or perpetual.
• Define device policy: one device, up to N devices, or manual transfer.
• Define offline grace policy and revocation timing.
• Persist these as explicit backend config.

1. Configure Whop assets

• Configure product and plans; confirm each

  purchase_url

  .
• Create API key with minimum scopes required by the chosen endpoints.
• Configure webhook endpoint and secret.
• Enable at least:

  membership.activated

  ,

  membership.deactivated

  ,

  membership.cancel_at_period_end_changed

  .

1. Implement backend contract

• Implement

  POST /api/license/activate

  that receives license input and

  hwid

  , then calls Whop license validation.
• Implement

  POST /api/webhooks/whop

  and verify signature before processing payload.
• Store entitlements keyed by Whop membership id and user id.
• Make webhook handling idempotent.

1. Implement app activation

• Build input UI for license key and loading/error states.
• Send activation requests only to backend endpoints.
• Store only activation status, timestamps, and non-secret metadata in app storage.
• Present user-safe messages for invalid license, conflict, and connectivity failures.

1. Implement periodic validation

• Revalidate on launch and on time interval (for example every 24h).
• Reuse the same metadata strategy used during activation.
• If offline, apply a bounded grace window before disabling paid access.

1. Implement cancellation and revocation sync

• Revoke local entitlement on

  membership.deactivated

  .
• Update renewal state on cancel-at-period-end changes.
• Treat webhook events as source of truth for passive status changes.

1. Complete release checks

• Test activation success, mismatch, and not-found cases.
• Test webhook signature pass/fail handling.
• Test transfer/reset behavior if supported by product policy.
• Test offline grace expiration behavior.

Implementation Rules

• Read

  references/implementation-playbook.md

  for endpoint matrix, payloads, and error mappings.
• Read

  references/platform-recipes.md

  for Node, Python, and Swift implementation recipes.
• Use

  scripts/verify_whop_webhook.py

  to test signature verification with captured payloads.
• Prefer current official Whop docs when endpoint versions differ from existing code.
• Keep structured logs with request id, membership id, event type, HTTP status, and API error body.

Output Requirements

1. Deliver backend route(s), webhook handler(s), and app activation flow updates.
2. Add or update automated tests for activation, webhook verification, and revocation.
3. Document security-sensitive implementation choices in changed files.
4. Return a checklist that separates completed items from pending items.