app_installation.created cuando una cuenta la instala y app_installation.deleted cuando una cuenta la elimina. Cada instalación también guarda dos valores que solo tu app puede cambiar. external_id vincula la instalación con un registro de tu sistema, y metadata contiene valores pequeños, como un cursor de sincronización.
Una tienda online que cobra pagos a través de Whop
Esta guía sigue una app inventada. Market Lane es un creador de tiendas online, y su app de Whop permite que un negocio cobre pagos en su tienda de Market Lane a través de Whop. Cada tienda tiene un identificador, comoriver-coffee, y cada checkout en Market Lane empieza con ese identificador.
Market Lane necesita saber tres cosas:
- Cuándo un negocio instala la app, para poder conectar la tienda del negocio.
- Qué cuenta de Whop recibe el pago cuando empieza un checkout en una tienda.
- Cuándo un negocio elimina la app, para que su tienda deje de ofrecer Whop en el checkout.
1
Solicita los permisos que necesita tu app
En los permisos de tu app, solicita
checkout_configuration:create para crear checkouts en la cuenta y webhook_receive:payments para enterarte de cuándo se pagan. El negocio aprueba ambos cuando instala la app.2
Suscribe el webhook de tu app
Crea un webhook que pertenezca a tu app, no a tu cuenta: establece La clave necesita
resource_id con el ID de tu app. Recibe los eventos de instalación de cada cuenta que instala tu app, además de los eventos de pago que esas cuentas concedieron.developer:manage_webhook en la cuenta propietaria de la app. Guarda el webhook_secret de la respuesta y verifica cada entrega como se describe en Webhooks.Solo los webhooks propios de tu app reciben eventos de instalación. Los webhooks de una cuenta nunca los reciben, ni siquiera para las apps instaladas en esa cuenta.3
Conecta la tienda cuando un negocio instala la app
app_installation.created lleva la instalación en data. El account_id del sobre es el negocio que instaló la app:river-coffee, Market Lane guarda el identificador en la instalación como external_id:4
Encuentra la cuenta cuando empieza un checkout
Un comprador hace el checkout en El resultado tiene como máximo una instalación, y su
river-coffee. La solicitud solo lleva el identificador de la tienda, así que Market Lane busca la instalación por external_id:account.id es la cuenta que recibe el pago. Market Lane crea un checkout en esa cuenta con POST /checkout_configurations, pone su propio ID de pedido en metadata y envía al comprador a la purchase_url. Market Lane no mantiene ninguna tabla de identificadores de tienda y cuentas de Whop, porque la instalación es la correspondencia.5
Marca el pedido como pagado
payment.succeeded llega al mismo webhook. Su account_id es el negocio de la tienda y el pago lleva los metadata del checkout, así que Market Lane encuentra el pedido por su ID y lo marca como pagado.6
Desactiva los pagos de Whop cuando el negocio elimina la app
app_installation.deleted llega en cuanto un negocio elimina tu app. Market Lane deja de ofrecer Whop en el checkout de river-coffee de inmediato, para que ningún comprador llegue a un checkout que fallaría. La instalación deja de aparecer en GET /app_installations y tu app ya no puede actuar sobre esa cuenta.7
Vuelve a conectar al reinstalar
Si el negocio vuelve a instalar la app, recibes otro
app_installation.created. Es la misma instalación: el id, created_at, external_id y metadata vuelven todos. Market Lane ve external_id: "river-coffee" en la carga útil y reactiva los pagos de Whop para esa tienda, sin pedir al negocio que la vuelva a conectar.Guarda tu propio ID en una instalación
external_ides único entre las instalaciones de tu app. Establecer un valor que ya tiene otra instalación devuelve un409, así que dos negocios nunca pueden reclamar la misma tienda. Los valores distinguen mayúsculas y minúsculas:River-Coffeeyriver-coffeeson distintos.metadatase fusiona. Las claves que envías se establecen, una clave con valornullse elimina, las claves que omites no cambian y{}borra todas las claves. Los valores son cadenas.- Una instalación eliminada conserva su
external_id. Mientras un negocio tenga tu app eliminada, ninguna otra instalación de tu app puede tomar ese valor. Si el negocio vuelve a instalar la app, el valor regresa con ella. - No guardes secretos. Tu cuenta de desarrollador puede leer
metadatayexternal_id.
Gestionar eventos repetidos
- Cuenta con repeticiones. Un negocio puede instalar, eliminar y volver a instalar tu app. Trata un
app_installation.createdde una instalación que ya conoces como una reinstalación. - Ignora los duplicados por
webhook-id. Whop reintenta las entregas que no obtienen una respuesta2xx, y un reintento conserva el mismowebhook-id.
Quién puede leer las instalaciones
Próximos pasos
Webhooks
Verifica firmas, gestiona reintentos y consulta todos los eventos.
Referencia de la API de instalaciones de apps
Todos los campos y endpoints de las instalaciones de apps.
Aceptar pagos
Crea checkouts y entrega pedidos a partir de
payment.succeeded.Permisos
Declara los permisos que tu app solicita al instalarse.

