Do this with AI
Install the developer-hub-app-architect skill from Contentstack agent skills and connect the App Integration Admin profile in MCP Profile Hub. Then ask your agent:
Check my app installations and webhook settings against the go-live checklist, and list what is still missing before I make the app available to other stacks.
New to this? Set up your AI workbench first.
Hosting and going live
Up to now the app has run from localhost:3000. That works for you and nobody else. This chapter moves it to a production URL, adds the security checks that matter once real editors use it, and closes with the checklist to run before you hand the app to anyone.
What you'll learn
How to host the app on Launch or on your own infrastructure
How to deploy with csdx app:deploy
How to verify signed requests
How to receive app lifecycle webhooks
What to check before go-live
Host on Launch
The Hosting tab in Developer Hub offers two options: Hosting with Launch and Custom Hosting. Launch is the low-overhead default. Connect a GitHub or Bitbucket repository, or upload a ZIP, and Launch builds and serves the app. The Hosting tab shows the deployment status and links to the Launch project.
One setting catches most people. Launch defaults the output directory to ./build, and the Vite boilerplate builds to dist. Set the output directory to ./dist in the Launch project or the deploy succeeds and serves nothing.
You can do the same from the terminal:
csdx app:deploy --org <org-uid> --app-uid <app-uid> --hosting-type hosting-with-launch --launch-project newWith --launch-project new, the command creates a Launch project and connects it to the app. Use existing to pick one you already have. An app connects to one Launch project at a time, and a Launch project to one app. If you want more control over Launch deployments from CI, see deploy from CI with the Launch CLI and API.
Host it yourself
Pick Custom Hosting and enter your app URL, or run:
csdx app:deploy --org <org-uid> --app-uid <app-uid> --hosting-type custom-hosting --app-url https://apps.example.com/seo-helperAny static host works. The one requirement is a single-page app fallback: every location path, such as /entry-sidebar, must serve index.html. The boilerplate ships a vercel.json for Vercel. Other hosts need their own rewrite rule.
Contentstack concept: Changing hosting is a manifest change and creates a new version. Deploying new code to the same URL is not. It is live for every installation the moment your host serves it, so keep a staging app and a production app if you need a safe place to test.
Verify signed requests
When a location has signed: true, Contentstack appends an app-token query parameter to the iframe URL. The value is a JWT signed with RS256. Its payload includes app_uid, installation_uid, organization_uid, user_uid, region and, for stack apps, stack_api_key.
Verify it before you trust anything the frontend sends to your backend. The public key is served at /.well-known/public-keys.json on the Contentstack app host for your region, for example https://app.contentstack.com/.well-known/public-keys.json, under the signing-key property.
import jwt from "jsonwebtoken";
const keys = await fetch("https://app.contentstack.com/.well-known/public-keys.json").then((r) => r.json());
export function verifyAppToken(token: string | null) {
if (!token) throw new Error("Missing app-token");
const payload = jwt.verify(token, keys["signing-key"], { algorithms: ["RS256"] }) as {
installation_uid: string;
stack_api_key?: string;
};
return payload;
}Three rules make this check worth having:
Fail closed. A missing token on a signed location is an error, not a reason to skip the check.
Scope data by the token's installation_uid and stack_api_key, never by IDs from the request body.
Do not use the token as a session. It expires after a few minutes. Verify it once and create your own session from the payload.
Cache the public key, and fetch it from the host for the region your installation runs in.
Receive lifecycle webhooks
The Webhooks tab subscribes your app to events for every installation, without anyone setting up stack webhooks by hand. Stack apps get App Events and Stack Events. Organization apps get App Events only. App Events cover installs, uninstalls and configuration updates, which is what you need to provision and clean up per-installation state in your backend.
Set a public notification URL (localhost is rejected), add HTTP Basic Auth or custom headers if you want, and pick the events. Add people to notify, because the circuit breaker disables a webhook that keeps failing and emails those addresses. Webhook delivery logs appear on the app configuration screen of each installation.
Verify the signature in the X-Contentstack-Request-Signature header before you act on a payload, as described in securing your app. Treat the body of an update event as sensitive. Do not log it raw or forward it to other tools.
Go-live checklist
Run through this list before you share the app beyond your own team.
Manifest and locations
Every declared location renders on a real installation, and unused boilerplate locations are removed.
Every path matches a route.
signed: true is set on each meta entry that handles data.
App Permissions and OAuth scopes are the minimum your code calls.
Security and configuration
The app-token is verified on every signed location and on your backend, and a missing token fails.
Secrets live in serverConfiguration. Nothing secret is in configuration, client environment variables or the build output.
serverConfiguration is only sent when a secret is set or cleared.
Every rewrite and mapping was tested from the app with a real stored value.
Hosting
The Hosting tab points at the production URL, not localhost or a tunnel.
The Launch output directory is ./dist for a Vite build.
Every location path serves index.html.
Releases
You know the current manifest version, and existing installations have been told about updates that add locations or webhooks.
For a public Marketplace listing, you have the name, icon, descriptions, screenshots, documentation, privacy policy and a test organization ready for review.
Key takeaways
Host on Launch with the output directory set to ./dist, or on any static host with a single-page app fallback.
csdx app:deploy connects hosting from the terminal, for Launch or a custom URL.
Code deploys are live immediately. Only manifest changes are versioned.
Verify the app-token JWT with RS256, fail closed, and never use it as a session.
Use app lifecycle webhooks to provision and clean up per-installation state, and verify their signatures.
Frequently asked questions
Does deploying new code create a new app version?
No. Developer Hub versions the manifest, not your code. New code is live for every installation as soon as your host serves it.
Can I use localhost as a webhook URL?
No. The webhook URL must be a public address. Use a tunnel or a deployed endpoint while you develop.
Can I use the app-token JWT as a session?
No. It expires after a few minutes. Verify it, then build your own session from its payload.