Install and Uninstall Events for Custom Apps

A user finds your app in the Apps library, reviews the permissions it requests, and confirms the install. After that, Blnk Cloud sends an event to your app so you can provision the installation on your side. Here’s what happens during installation:

The user clicks Install from the app details page.
The user reviews and approves the permissions.
Blnk Cloud creates a scoped API key for the installation.
Blnk Cloud sends the install event to your backend via the callback URL.
Your app stores the install details and returns a 2xx response.
If the response succeeds, the app becomes active in Cloud.

See Best practices for how to protect API keys, handle duplicate events safely, and prepare for production.

Handling the install event

An install event tells your app that a user has connected it to a specific workspace and Cloud instance. The install is already scoped to that context in Blnk”you do not receive a separate organization field in the callback. Blnk Cloud sends a payload like this:

install_payload.json

{
  "installed_app_id": "instapp_...",
  "app_id": "app_...",
  "instance_id": "inst_...",
  "api_key": "blnk_...",
  "api_key_prefix": "blnk_abc",
  "granted_permissions": ["data:read", "data:write"],
  "idempotency_key": "install:instapp_..."
}

Field	Description
`installed_app_id`	The ID for this specific app installation.
`app_id`	The ID of the app that was installed.
`instance_id`	The Cloud instance where the app was installed.
`api_key`	The scoped API key your backend uses to call Cloud APIs for this install.
`api_key_prefix`	A safe prefix for identifying the key without exposing the full secret.
`granted_permissions`	The permissions the user approved during installation.
`idempotency_key`	A unique key for this install event. Use it to avoid processing the same event twice.

Once you receive the install event, you need to save the install details so your backend can use them later.

Note: If your app does not return a 2xx response within 10 seconds, Blnk cancels the installation, revokes the API key, and the install fails.

For our Stripe Sync app, our install handler looks like this:

routes.ts

app.post("/api/callback", async (req, res) => {
  const event = req.body;

  if (event.idempotency_key?.startsWith("install:")) {

    // Never persist the raw `api_key` in your database " encrypt it at rest (see Codebase setup).
    await installs.save({
      installed_app_id: event.installed_app_id,
      app_id: event.app_id,
      instance_id: event.instance_id,
      api_key_encrypted: encryptSecret(event.api_key),
      api_key_prefix: event.api_key_prefix,
      granted_permissions: event.granted_permissions,
      status: "active",
      idempotency_key: event.idempotency_key
    });

    return res.status(200).json({ ok: true });
  } 
});

Use whatever encryption or key-management approach fits your stack before you write the secret to your database.

Handling the uninstall event

When a user uninstalls your app, Blnk Cloud sends an uninstall event to the same callback URL. If your app returns 2xx, Cloud marks the install uninstalled and revokes the app’s API key. If the callback fails, the uninstall does not complete and the API key remains valid. Your app should use this event to stop treating the installation as active. You can also clean up any resources you created for that organization or instance.

uninstall_payload.json

{
  "installed_app_id": "instapp_...",
  "app_id": "app_...",
  "instance_id": "inst_...",
  "uninstalled_at": "2026-04-21T12:00:00Z",
  "idempotency_key": "uninstall:instapp_..."
}

For the Stripe Sync app, uninstalling should mark the installation as inactive so the backend stops using the stored install record.

routes.ts

app.post("/api/callback", async (req, res) => {
  const event = req.body;

  if (event.idempotency_key?.startsWith("uninstall:")) {
    await installs.update({
      installed_app_id: event.installed_app_id,
      status: "inactive"
    });

    return res.status(200).json({ ok: true });
  }
});

You can also choose to delete encrypted keys, remove portal sessions, or clean up instance-specific resources.

Handling duplicate events

Cloud sends one install or uninstall request per event, with a 10 second timeout. Your handler should still be safe to run more than once. Use the idempotency_key to check whether you have already processed the event. If you have already processed the event, return a 200 response to avoid processing the event again:

routes.ts

app.post("/api/callback", async (req, res) => {
  const event = req.body;

  const existingEvent = await checkIfEventProcessed(event.idempotency_key);

  if (existingEvent) {
    return res.status(200).json({ ok: true });
  }

  // Process the event
});

Test the installation flow

Before moving to app development, test the install and uninstall flow from Cloud.

Register your app.
Install the app from the Apps library.
Confirm your callback URL receives the install event.
Confirm your callback URL returns a 2xx response.
Confirm the install is active in your database.
Uninstall the app from Cloud.
Confirm your callback URL receives the uninstall event.
Confirm the install is no longer active in your database.

Run the example Stripe Sync app

Reference Stripe sync implementation.

Start Here

Build An App

Set Up Install and Uninstall Events

Handling the install event

Handling the uninstall event

Handling duplicate events

Test the installation flow

Run the example Stripe Sync app

​Handling the install event

​Handling the uninstall event

​Handling duplicate events

​Test the installation flow

Run the example Stripe Sync app

Handling the install event

Handling the uninstall event

Handling duplicate events

Test the installation flow