app_installation.created lorsqu’un compte l’installe et app_installation.deleted lorsqu’un compte la supprime. Chaque installation stocke également deux valeurs que seule votre application peut modifier. external_id relie l’installation à un enregistrement de votre système, et metadata contient de petites valeurs, comme un curseur de synchronisation.
Une boutique en ligne qui encaisse des paiements via Whop
Ce guide suit une application fictive. Market Lane est un outil de création de boutiques en ligne, et son application Whop permet à une entreprise d’encaisser des paiements sur sa boutique Market Lane via Whop. Chaque boutique possède un identifiant, commeriver-coffee, et chaque paiement sur Market Lane commence par cet identifiant.
Market Lane doit connaître trois choses :
- Le moment où une entreprise installe l’application, afin de connecter la boutique de l’entreprise.
- Le compte Whop qui encaisse le paiement lorsqu’un paiement commence sur une boutique.
- Le moment où une entreprise supprime l’application, afin que sa boutique cesse de proposer Whop au moment du paiement.
1
Demander les permissions dont votre application a besoin
Dans les permissions de votre application, demandez
checkout_configuration:create pour créer des paiements sur le compte, et webhook_receive:payments pour être notifié lorsqu’ils sont réglés. L’entreprise approuve les deux lorsqu’elle installe l’application.2
Abonner le webhook de votre application
Créez un webhook qui appartient à votre application, et non à votre compte : définissez La clé doit disposer de
resource_id sur l’ID de votre application. Il reçoit les événements d’installation de chaque compte qui installe votre application, ainsi que les événements de paiement autorisés par ces comptes.developer:manage_webhook sur le compte propriétaire de l’application. Conservez le webhook_secret de la réponse et vérifiez chaque livraison comme décrit dans Webhooks.Seuls les webhooks propres à votre application reçoivent les événements d’installation. Les webhooks d’un compte ne les reçoivent jamais, même pour les applications installées sur ce compte.3
Connecter la boutique lorsqu'une entreprise installe l'application
app_installation.created contient l’installation dans data. Le champ account_id de l’enveloppe correspond à l’entreprise qui a installé l’application :river-coffee, Market Lane enregistre l’identifiant sur l’installation en tant que external_id :4
Trouver le compte lorsqu'un paiement commence
Un client passe commande sur Le résultat contient au plus une installation, et son
river-coffee. La requête ne contient que l’identifiant de la boutique : Market Lane recherche donc l’installation par external_id :account.id est le compte qui encaisse le paiement. Market Lane crée un paiement sur ce compte avec POST /checkout_configurations, place son propre ID de commande dans metadata et redirige le client vers la purchase_url. Market Lane ne conserve aucune table de correspondance entre identifiants de boutique et comptes Whop, car l’installation fait office de correspondance.5
Marquer la commande comme payée
payment.succeeded arrive sur le même webhook. Son account_id est l’entreprise de la boutique, et le paiement contient les metadata du paiement initial : Market Lane retrouve donc la commande grâce à son ID et la marque comme payée.6
Désactiver les paiements Whop lorsque l'entreprise supprime l'application
app_installation.deleted arrive dès qu’une entreprise supprime votre application. Market Lane cesse immédiatement de proposer Whop au moment du paiement sur river-coffee, afin qu’aucun client n’atteigne un paiement voué à l’échec. L’installation n’apparaît plus dans GET /app_installations, et votre application ne peut plus agir sur ce compte.7
Reconnecter lors d'une réinstallation
Si l’entreprise installe à nouveau l’application, vous recevez un nouvel événement
app_installation.created. Il s’agit de la même installation : id, created_at, external_id et metadata sont tous restaurés. Market Lane voit external_id: "river-coffee" dans la charge utile et réactive les paiements Whop pour cette boutique, sans demander à l’entreprise de la reconnecter.Stocker votre propre ID sur une installation
external_idest unique parmi les installations de votre application. Définir une valeur déjà utilisée par une autre installation renvoie une erreur409: deux entreprises ne peuvent donc jamais revendiquer la même boutique. Les valeurs sont sensibles à la casse :River-Coffeeetriver-coffeesont différentes.metadataest fusionné. Les clés que vous envoyez sont définies, une clé définie surnullest supprimée, les clés que vous omettez ne changent pas, et{}efface toutes les clés. Les valeurs sont des chaînes de caractères.- Une installation supprimée conserve son
external_id. Tant qu’une entreprise a supprimé votre application, aucune autre installation de votre application ne peut prendre cette valeur. Si l’entreprise installe à nouveau l’application, la valeur est restaurée avec elle. - Ne stockez pas de secrets. Votre compte développeur peut lire
metadataetexternal_id.
Gérer les événements répétés
- Attendez-vous à des répétitions. Une entreprise peut installer, supprimer, puis réinstaller votre application. Traitez un
app_installation.createdportant sur une installation que vous connaissez déjà comme une réinstallation. - Ignorez les doublons grâce au
webhook-id. Whop relance les livraisons qui ne reçoivent pas de réponse2xx, et une relance conserve le mêmewebhook-id.
Qui peut lire les installations
Étapes suivantes
Webhooks
Vérifiez les signatures, gérez les relances et consultez tous les événements.
Référence de l'API App Installations
Tous les champs et endpoints des installations d’applications.
Accepter des paiements
Créez des paiements et livrez les commandes à partir de
payment.succeeded.Permissions
Déclarez les permissions que votre application demande lors de l’installation.

