The external install flow lets you trigger a Wix app installation from outside the Wix App Market, editor, or site dashboard. For example, from a published Wix site or non-Wix site. When triggered externally, Wix supports the functionality to specify a post-installation redirect, track custom state, and provides OAuth credentials to simplify integrating external app services with Wix sites.
To support the external install flow:
When a site visitor navigates to the URL, the following flow starts:
The external install flow also supports custom state, which is data you can pass as query parameters in the callback URL. Wix preserves your state throughout the external install flow and returns it to the callback handler.
Learn more about setting up the external install flow.
To start the external install flow, you must build and expose an installation URL. Build the URL by appending query parameters to the base URL using standard query string syntax:
The installation URL supports the following query parameters:
| Query parameter | Required | Description |
|---|---|---|
appId | Yes | The app ID of the app you want to install. Triggers the standard install flow for the specified app. |
postInstallationUrl | No | Your callback URL, which you can specify at runtime. After the install completes, Wix redirects the Wix user to this URL and appends its own query parameters. Wix also preserves any query parameters you include. |
shareUrlId | For unlisted apps | The unique ID for a share install link. Required when your app is unlisted and you use the external install flow with postInstallationUrl. |
For unlisted apps, site visitors install your app through a share install link you create in your app dashboard. Include the link's unique ID in the installation URL as shareUrlId so Wix can resolve the install path that would otherwise come from the App Market listing. Learn how to extract the ID and add it to your installation URL in Set Up the External Install Flow.
Important:
The postInstallationUrl must be an encoded URI component.
After the install completes, Wix redirects the Wix user to your postInstallationUrl and appends query parameters. Implement a callback handler to receive and process them.
Important: Your callback handler method must use HTTPS.
The following table describes the query parameters Wix appends to the redirect URL:
| Query parameter | Description |
|---|---|
appId | Your Wix app ID. |
tenantId | The ID of the Wix site that installed the app. |
instanceId | A unique ID for this app installation, sent as plain text in the redirect URL. |
signedInstance | A signed and encoded copy of the app instance data, included on successful installs. |
| Custom state | Query parameters you included in the postInstallationUrl. |
For example, a redirect URL looks like this:
Warning: Verify signedInstance before you trust instanceId or store it. Query parameters can be forged, so instanceId on its own isn't proof of a successful install. Parse and verify signedInstance to confirm the install, then treat instanceId as a permanent credential for this app-site connection and store it securely.
Use the instanceId from your callback handler to create OAuth access tokens that grant access to the permissions you've defined in your app dashboard and enable your backend to call Wix APIs on behalf of the installed app.
Last updated: 6 July 2026