Skip to main content
Een app-installatie is één installatie van je app op één Whop-account. Je app ontvangt app_installation.created wanneer een account de app installeert en app_installation.deleted wanneer een account de app verwijdert. Elke installatie slaat ook twee waarden op die alleen je app kan wijzigen. external_id koppelt de installatie aan een record in je systeem, en metadata bevat kleine waarden, zoals een sync-cursor.

Een webwinkel die betalingen via Whop ontvangt

Deze gids volgt een verzonnen app. Market Lane is een tool om webwinkels te bouwen, en met de Whop-app ervan kan een bedrijf betalingen in zijn Market Lane-winkel via Whop ontvangen. Elke winkel heeft een handle, zoals river-coffee, en elke checkout op Market Lane begint met die handle. Market Lane moet drie dingen weten:
  1. Wanneer een bedrijf de app installeert, zodat de winkel van het bedrijf kan worden gekoppeld.
  2. Welk Whop-account de betaling ontvangt wanneer er een checkout start in een winkel.
  3. Wanneer een bedrijf de app verwijdert, zodat de winkel Whop niet langer aanbiedt bij de checkout.
1

Vraag de permissies aan die je app nodig heeft

Vraag in de permissies van je app checkout_configuration:create aan om checkouts op het account aan te maken, en webhook_receive:payments om te horen wanneer ze zijn betaald. Het bedrijf keurt beide goed bij het installeren van de app.
2

Abonneer de webhook van je app

Maak één webhook aan die bij je app hoort, niet bij je account: stel resource_id in op de ID van je app. Deze webhook ontvangt de installatie-events van elk account dat je app installeert, plus de betalingsevents waarvoor die accounts toestemming hebben gegeven.
De sleutel heeft developer:manage_webhook nodig op het account dat eigenaar is van de app. Sla de webhook_secret uit de response op en verifieer elke levering zoals beschreven in Webhooks.Alleen de eigen webhooks van je app ontvangen installatie-events. De webhooks van een account doen dat nooit, ook niet voor de apps die op dat account zijn geïnstalleerd.
3

Koppel de winkel wanneer een bedrijf de app installeert

app_installation.created bevat de installatie in data. De account_id van de envelope is het bedrijf dat de app heeft geïnstalleerd:
Market Lane vraagt het bedrijf welke winkel moet worden gekoppeld. Wanneer het river-coffee kiest, slaat Market Lane de handle op de installatie op als external_id:
4

Zoek het account op wanneer een checkout start

Een klant rekent af in river-coffee. Het request bevat alleen de handle van de winkel, dus Market Lane zoekt de installatie op via external_id:
Het resultaat bevat maximaal één installatie, en de account.id daarvan is het account dat de betaling ontvangt. Market Lane maakt op dat account een checkout aan met POST /checkout_configurations, zet zijn eigen bestel-ID in metadata en stuurt de klant naar de purchase_url. Market Lane houdt geen tabel bij van winkelhandles en Whop-accounts, want de installatie is de koppeling.
5

Markeer de bestelling als betaald

payment.succeeded komt binnen op dezelfde webhook. De account_id is het bedrijf van de winkel, en de betaling bevat de metadata uit de checkout, dus Market Lane vindt de bestelling via de ID en markeert die als betaald.
6

Schakel Whop-betalingen uit wanneer het bedrijf de app verwijdert

app_installation.deleted komt binnen zodra een bedrijf je app verwijdert. Market Lane stopt direct met het aanbieden van Whop bij de checkout van river-coffee, zodat geen enkele klant bij een checkout uitkomt die zou mislukken. De installatie verschijnt niet meer in GET /app_installations, en je app kan niet langer acties uitvoeren op dat account.
7

Opnieuw koppelen bij een herinstallatie

Als het bedrijf de app opnieuw installeert, ontvang je opnieuw een app_installation.created. Het is dezelfde installatie: de id, created_at, external_id en metadata komen allemaal terug. Market Lane ziet external_id: "river-coffee" in de payload en zet Whop-betalingen weer aan voor die winkel, zonder het bedrijf te vragen de winkel opnieuw te koppelen.

Je eigen ID op een installatie opslaan

  • external_id is uniek binnen alle installaties van je app. Een waarde instellen die een andere installatie al heeft, geeft een 409, dus twee bedrijven kunnen nooit dezelfde winkel claimen. Waarden zijn hoofdlettergevoelig: River-Coffee en river-coffee zijn verschillend.
  • metadata wordt samengevoegd. De sleutels die je meestuurt worden ingesteld, een sleutel met de waarde null wordt verwijderd, sleutels die je weglaat veranderen niet, en {} wist alle sleutels. Waarden zijn strings.
  • Een verwijderde installatie behoudt haar external_id. Zolang een bedrijf je app heeft verwijderd, kan geen andere installatie van je app die waarde gebruiken. Als het bedrijf de app opnieuw installeert, komt de waarde mee terug.
  • Sla geen geheimen op. Je developer-account kan metadata en external_id lezen.

Herhaalde events afhandelen

  • Houd rekening met herhalingen. Een bedrijf kan je app installeren, verwijderen en opnieuw installeren. Behandel app_installation.created voor een installatie die je al kent als een herinstallatie.
  • Negeer duplicaten op basis van webhook-id. Whop probeert leveringen die geen 2xx-response krijgen opnieuw, en een herhaalpoging behoudt dezelfde webhook-id.

Wie installaties kan lezen

Volgende stappen

Webhooks

Verifieer handtekeningen, verwerk herhaalpogingen en bekijk alle events.

API-referentie voor app-installaties

Alle velden en endpoints voor app-installaties.

Betalingen accepteren

Maak checkouts aan en lever bestellingen uit vanuit payment.succeeded.

Permissies

Geef aan welke permissies je app bij installatie aanvraagt.