#How to set WORKOS_WEBHOOK_SECRET on preview deployments created via convex deploy --preview-create?

4 messages · Page 1 of 1 (latest)

weak oxide
#

The managed AuthKit setup in convex.json auto-provisions WORKOS_CLIENT_ID, WORKOS_API_KEY, and WORKOS_ENVIRONMENT_ID on preview deployments, but WORKOS_WEBHOOK_SECRET is not included. At runtime, the @convex-dev/workos-authkit
component fails because it can't find WORKOS_WEBHOOK_SECRET in the deployment's environment variables.

I'm passing WORKOS_WEBHOOK_SECRET as a build-time env var in my GitHub Actions workflow, but convex deploy doesn't have an --env-var-set flag, and convex env set doesn't support targeting preview deployments (only --prod or dev).

Is there a way to either:

  1. Have the managed AuthKit provisioning automatically set WORKOS_WEBHOOK_SECRET on preview deployments (similar to how it handles the other WorkOS env vars)?
  2. Target a preview deployment with convex env set from CI?
  3. Use project-level AuthKit environments so all deployments share the same webhook secret?

Using [email protected] and @convex-dev/[email protected].

weary elkBOT
#

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

#

Based on the knowledge sources, here's what I can confirm about your options:

Option 2: Target a preview deployment with convex env set from CI

This is the most directly supported approach. The convex env set command supports a --preview-name flag for targeting preview deployments:

npx convex env set --preview-name $YOUR_BRANCH_NAME WORKOS_WEBHOOK_SECRET $WORKOS_WEBHOOK_SECRET

In a Vercel environment, the default preview name used by Convex is the Git branch name ($VERCEL_GIT_COMMIT_REF). For GitHub Actions, you'd use the equivalent branch name variable (e.g., $GITHUB_HEAD_REF or $GITHUB_REF_NAME). [VERCEL_URL thread]

Your CI workflow would look something like:

npx convex deploy --preview-create $GITHUB_HEAD_REF
npx convex env set --preview-name $GITHUB_HEAD_REF WORKOS_WEBHOOK_SECRET $WORKOS_WEBHOOK_SECRET

Option 3: Project-level default environment variables

You can set project-level default environment variables for preview deployments in the Convex dashboard under Project Settings. These defaults are applied when a new preview deployment is created. [Project Env Vars]

Important caveat: These defaults only apply to newly created deployments — they are not kept in sync with existing ones. [Default env vars thread]

So if you set WORKOS_WEBHOOK_SECRET as a project default for preview deployments, each new --preview-create call should pick it up automatically.

Option 1: Managed AuthKit auto-provisioning

#

The knowledge sources do not indicate that the managed AuthKit provisioning in convex.json supports automatically setting WORKOS_WEBHOOK_SECRET. The auto-configuration handles WORKOS_CLIENT_ID, WORKOS_API_KEY, and redirect/CORS configuration, but webhook secrets are not mentioned as part of that flow. [Auto-provision docs]

Recommended approach: Use Option 3 (set WORKOS_WEBHOOK_SECRET as a project-level default for preview deployments in the dashboard) combined with Option 2 as a fallback in CI if needed. The project default is the least friction since it requires no per-deployment CI steps.

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