Set Up the External Install Flow

The external install flow lets you trigger a Wix app install flow from outside the App Market, editor, or site dashboard, as well as extend the standard install flow with a post-install redirect and state tracking.

This article guides you through building the installation URL and implementing the callback handler to handle the post-install redirect and manage state.

The end result will be:

  • An installation URL that includes your callback URL and custom state.
  • A callback handler that receives the redirect, verifies the install succeeded, and uses the state you passed.

Step 1 | Get the share URL ID for unlisted apps

Note: If your app is listed in the Wix App Market, skip this step.

If your app is unlisted, include a shareUrlId in the installation URL. This ID comes from the share install link you create in your app dashboard.

At the end of this step, you have your shareUrlId to add to the installation URL.

To get the shareUrlId:

  1. Create a share install link in your app dashboard.
  2. Open the install link in your browser. A short link like https://wix.to/g2b6Luf redirects to a URL similar to https://www.wix.com/app-market/install/9344930f-1a50-4edd-b7ba-efc1af3ac304.
  3. Copy the GUID at the end of the resolved URL. This is your shareUrlId.

Step 2 | Build the installation URL

This step builds the installation URL with an appId and postInstallationUrl. For unlisted apps, also add shareUrlId.

At the end of this step, you have an installation URL that supports redirects and any query parameters you add.

To build the installation URL:

  1. Get your appId from the app dashboard. On your app's home page, click More Actions and select View ID & keys.

  2. Choose your callback URL. Use a route on your server that handles the redirect.

  3. Add state to your callback URL. State is custom data you want to pass through the install flow, such as a user ID or return path. Add it as query parameters to your callback URL.

    The following example creates the callback URL and adds a state object as a query parameter:

    Copy

Important: If your state contains sensitive data, encrypt it before adding it to the URL.

  1. Encode the callback URL with encodeURIComponent.

  2. Build the installation URL with appId and set the postInstallationUrl parameter to your encoded callback URL. If your app is unlisted, also add shareUrlId. Provide the installation URL, such as by attaching it to a button on a site. When a site visitor navigates to the URL, such as by clicking on a button, it will trigger the external install flow.

The example below shows the complete code for building the installation URL.

Step 3 | Build the callback handler

This step implements the callback handler at your callback URL. After a site visitor completes the standard install flow, Wix redirects them to your callback URL. Wix appends query parameters to the URL and preserves any query parameters you added.

At the end of this step, you have a working callback handler and access to the query parameters and state you passed.

The following examples use a Node.js server with Express. If you use another framework or language, define a GET handler for your callback path and process the query parameters in the way your stack supports. You can also read the parameters client-side from the page URL using browser APIs.

Important: Your callback handler endpoint must use HTTPS.

To build the callback handler:

  1. Define a GET route for the path that matches your postInstallationUrl and read the query parameters. Wix sends signedInstance on successful installs so you can cryptographically verify the callback. The following example registers the route and reads the query parameters from the request.

    Copy

  2. Verify the install succeeded. Confirm both instanceId and signedInstance are present, then parse and verify signedInstance before you trust instanceId. If either parameter is missing, or if verification fails, the install failed, was canceled, or the callback is untrusted. The following example redirects to a cancellation page when either parameter is missing:

    Copy

  3. Use the query parameters and state as needed.

The example below shows the complete callback handler:

Copy

See also

Last updated: 6 July 2026

Did this help?