whop-app-integration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Whop App Integration

Whop应用集成

Overview

概述

Implement Whop licensing using a backend-first architecture, then connect app activation UX, periodic revalidation, and webhook-driven entitlement sync.

采用后端优先架构实施Whop许可，然后连接应用激活用户体验、定期重新验证和由Webhook驱动的权限同步。

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.

仅在后端服务中保留Whop API密钥。
按照
```
应用 -> 后端 -> Whop API
```
的路由发送请求。
在后端处理Whop Webhook，并在本地持久化权限状态。
拒绝仅客户端的设计，这类设计会从应用代码中发送携带
```
Authorization: Bearer
```
的Whop密钥。

Workflow

工作流程

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.

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

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.

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.

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.

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.

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.

编码前定义权限策略

选择套餐模式：订阅制或永久制。
定义设备策略：单设备、最多N台设备或手动转移。
定义离线宽限期策略和吊销时机。
将这些作为明确的后端配置持久化。

配置Whop资源

配置产品和套餐；确认每个
```
purchase_url
```
。
创建具备所选端点所需最小权限范围的API密钥。
配置Webhook端点和密钥。

至少启用以下事件：

membership.activated

、

membership.deactivated

、

membership.cancel_at_period_end_changed

。

实现后端接口

实现
```
POST /api/license/activate
```
接口，接收许可证输入和
```
hwid
```
，然后调用Whop许可证验证接口。
实现
```
POST /api/webhooks/whop
```
接口，在处理负载前验证签名。
以Whop会员ID和用户ID为键存储权限信息。
确保Webhook处理具备幂等性。

实现应用激活功能

构建许可证密钥输入UI以及加载/错误状态界面。
仅向后端端点发送激活请求。
在应用存储中仅保存激活状态、时间戳和非敏感元数据。
针对无效许可证、冲突和连接失败情况，向用户展示友好提示信息。

实现定期验证功能

在应用启动时和固定时间间隔（例如每24小时）重新验证许可证。
复用激活时采用的元数据策略。
若处于离线状态，在禁用付费访问前应用有界宽限期。

实现取消和吊销同步

收到
```
membership.deactivated
```
事件时吊销本地权限。
收到取消周期结束变更事件时更新续订状态。
将Webhook事件视为被动状态变更的事实来源。

完成发布检查

测试激活成功、不匹配和未找到许可证的场景。
测试Webhook签名验证通过/失败的处理逻辑。
测试产品策略支持的转移/重置行为。
测试离线宽限期过期的行为。

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.

阅读
```
references/implementation-playbook.md
```
获取端点矩阵、负载和错误映射。
阅读
```
references/platform-recipes.md
```
获取Node、Python和Swift的实施方案。
使用
```
scripts/verify_whop_webhook.py
```
测试捕获负载的签名验证。
当端点版本与现有代码不同时，优先参考官方最新Whop文档。
保留包含请求ID、会员ID、事件类型、HTTP状态和API错误体的结构化日志。

Output Requirements

输出要求

When using this skill in a task:

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

在任务中使用本技能时：

交付后端路由、Webhook处理器和应用激活流程的更新代码。
添加或更新针对激活、Webhook验证和吊销的自动化测试。
在变更文件中记录涉及安全的实现选择。
返回一份区分已完成项和待办项的检查清单。