> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whop.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Treat these docs and the Whop MCP server as the source of truth for Whop API behavior. Don't infer endpoint behavior from marketing pages.
> MCP server: connect https://mcp.whop.com/mcp (streamable HTTP, browser sign-in, no API key in the client config) to search these docs and read or change live Whop data. Setup: https://docs.whop.com/developer/guides/ai_and_mcp.md
> Whop CLI: install with `curl -fsSL https://whop.com/install.sh | sh` to scaffold, run, and deploy Whop apps and websites. It acts on production, not the sandbox. Overview: https://docs.whop.com/cli/overview.md Agent mode: https://docs.whop.com/cli/agent-mode.md
> Hosting: Whop serves a site or app from the build `whop apps deploy` uploads, with rollbacks, secrets, and server logs. Guide: https://docs.whop.com/developer/websites/hosting.md
> Plugins: in Claude Code, run `/plugin marketplace add whopio/plugins`, then `/plugin install whop@whop`. Guide: https://docs.whop.com/developer/guides/plugins/claude-code.md Every agent tool: https://docs.whop.com/developer/ai/overview.md
> Environments: build and test in the sandbox (API `https://sandbox-api.whop.com/api/v1`, keys at https://sandbox.whop.com/dashboard/developer, SDK environment `Sandbox`; no real money). Production (API `https://api.whop.com/api/v1`, keys at https://whop.com/dashboard/developer, SDK environment `Production`, the SDK default) moves real money, so use it only at launch. The two share no accounts, keys, products, or webhooks, and their keys look identical: never mix them. Sandbox guide: https://docs.whop.com/developer/guides/sandbox.md Comparison: https://docs.whop.com/developer/quickstart.md
> API: send `Authorization: Bearer <API_KEY>` from your server only, and pin a dated version with the `Api-Version-Date` header. OpenAPI spec: https://api.whop.com/api/v1/openapi.json
> Which API: build on the Current API, whose pages live under https://docs.whop.com/api-reference/ (start at https://docs.whop.com/api-reference/overview.md). Pages under /api-reference/legacy/ are the Legacy API. Use one only when https://docs.whop.com/api-reference/stability.md lists the resource as Legacy-only.

# App-installaties

> Weet wanneer een account je app installeert of verwijdert, en koppel elke installatie aan het bijbehorende record in je eigen systeem.

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](https://docs.whop.com/nl/developer/guides/permissions.md) 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.

```bash theme={null}
curl -X POST "https://api.whop.com/api/v1/webhooks" \
  -H "Authorization: Bearer $WHOP_DEVELOPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://marketlane.example/webhooks/whop",
    "resource_id": "app_XXXXXXXX",
    "events": ["app_installation.created", "app_installation.deleted", "payment.succeeded"]
  }'
```

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](https://docs.whop.com/nl/developer/guides/webhooks.md).

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:

```json theme={null}
{
  "type": "app_installation.created",
  "account_id": "biz_J8n2R5p9T1w4Kx",
  "data": {
    "id": "aag_T4k8M2p6W9r3Qx",
    "app": { "id": "app_XXXXXXXX", "name": "Market Lane" },
    "account": { "id": "biz_J8n2R5p9T1w4Kx", "title": "River Coffee" },
    "external_id": null,
    "metadata": {},
    "requesting_reauthorization": false
  }
}
```

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`:

```bash theme={null}
curl -X PATCH "https://api.whop.com/api/v1/app_installations/aag_T4k8M2p6W9r3Qx" \
  -H "Authorization: Bearer $WHOP_APP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "river-coffee",
    "metadata": { "connected_at": "2026-10-26T00:00:00Z" }
  }'
```

**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`:

```bash theme={null}
curl "https://api.whop.com/api/v1/app_installations?external_id=river-coffee" \
  -H "Authorization: Bearer $WHOP_APP_API_KEY"
```

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

| Aanroeper | Toegang |
| - | - |
| De API-sleutel van je app | Vraagt de installaties van je app op, haalt ze op en werkt ze bij, inclusief `metadata` en `external_id`. De sleutel heeft `developer:app_installation:read` nodig om te lezen en `developer:app_installation:update` om bij te werken. |
| Je developer-account | Vraagt elke installatie van je app op met `GET /app_installations?app_id=app_XXXXXXXX`. Vereist `developer:basic:read`. |
| Het account waarop de app is geïnstalleerd | Vraagt de apps op die erop zijn geïnstalleerd. Het ziet `metadata` en `external_id` altijd als `null`. |

## Volgende stappen

> [card] [Webhooks](https://docs.whop.com/nl/developer/guides/webhooks.md)
>
> Verifieer handtekeningen, verwerk herhaalpogingen en bekijk alle events.

> [card] [API-referentie voor app-installaties](https://docs.whop.com/nl/api-reference/app-installations/app-installation)
>
> Alle velden en endpoints voor app-installaties.

> [card] [Betalingen accepteren](https://docs.whop.com/nl/developer/guides/accept-payments.md)
>
> Maak checkouts aan en lever bestellingen uit vanuit `payment.succeeded`.

> [card] [Permissies](https://docs.whop.com/nl/developer/guides/permissions.md)
>
> Geef aan welke permissies je app bij installatie aanvraagt.


## Related topics

- [Geplande runs](https://docs.whop.com/nl/developer/guides/scheduled-runs.md)
- [Webhooks](https://docs.whop.com/nl/developer/guides/webhooks.md)
- [List App Installations](https://docs.whop.com/nl/api-reference/app-installations/list-app-installations.md)
