Clerk->Convex sync in preview/staging

[long osprey]

Maybe it's been asked before, but I can't find it.

I love the clerk->convex webhook example. I've done a lot of manual Firebase->Prisma syncing before, so this helps.

I've setup Clerk's dev env with the Convex Vercel Previews. Since the Clerk Previews start with an empty DB, are the preview envs of Convex predictable? I can't setup a long-lived staging environment can I? What's a graceful way to keep Convex aware of the Clerk logins since the previews won't be at a stable webhook url?

[nocturne bluff]

Hi @long osprey. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

---

You're asking about managing Clerk authentication with Convex preview deployments, which is a common challenge when working with these two services together.

Clerk and Convex Preview Deployments

Convex preview deployments are not predictable in the sense that they don't have stable URLs - they use randomly generated names (like "happy-animal-123.convex.cloud") rather than branch-based URLs. This makes webhook configuration challenging for preview environments.

For setting up Clerk with Convex preview deployments, here are some approaches:

1. Environment Variables for Preview Deployments

You can set environment variables for your preview deployments using the --preview-name flag with the Convex CLI:

npx convex env set --preview-name $VERCEL_GIT_COMMIT_REF CLERK_JWT_ISSUER_DOMAIN your-value

This allows you to configure the Clerk JWT issuer domain for each preview deployment based on a Discord thread.

2. Default Environment Variables

Convex allows you to set default environment variables that apply to all preview deployments:

npx convex env set --default CLERK_JWT_ISSUER_DOMAIN your-value

This approach is mentioned by a Convex support staff member as "the closest solution is using default environment variables, which apply to all new preview deployments, but also to all new dev deployments" in this Discord thread.

3. Alternative Authentication for Previews

Some developers opt to use a simpler authentication method just for preview environments:

• Enable email/password login only in preview/dev environments
• Create test user buttons that appear only in preview/dev
• This avoids the webhook complexity entirely for non-production environments

Long-lived Staging Environment

While Convex preview deployments are designed to be temporary (they're automatically cleaned up after 14 days), you can create a more permanent staging environment by using a separate Convex project:

"If you need a more permanent staging environment, you can use a separate Convex project, and deploy to it by setting the CONVEX_DEPLOY_KEY environment variable when running npx convex deploy." as mentioned in the Convex docs.

This would give you a stable URL for webhook configuration with Clerk's staging environment.

Hope this helps with your Clerk-Convex integration! Let me know if you need more specific guidance on any of these approaches.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

@vocal gust Kapa.ai is still learning and improving, please let me know how I did by reacting below.