Convex + Next.js Dual-Environment Secret Configuration

Problem

When using Convex with Next.js and internal API authentication (e.g., for webhook handlers), setting INTERNAL_API_SECRET only in .env.local is insufficient. Convex mutations that verify this secret will fail with "Unauthorized" because Convex runs in a separate environment and doesn't have access to Next.js environment variables.

Context / Trigger Conditions

• Webhook handler returns 500 with "Unauthorized" error
• Error stack trace points to a Convex mutation/query that checks process.env.INTERNAL_API_SECRET
• The secret IS correctly set in .env.local for Next.js
• Next.js API route successfully reads the secret and passes it to Convex
• Convex mutation fails because process.env.INTERNAL_API_SECRET is undefined in Convex runtime