Next.js Deployment Learnings: When Framework Defaults Silently Break External Integrations

Both of these were invisible in development and only surfaced in production. No exceptions thrown, no obvious errors — just silent failures at the boundary between our app and external services.

1. Auth middleware that corrupts webhook responses

Senquel uses Supabase SSR, which ships a middleware that calls supabase.auth.getUser() on every request to keep the session cookie fresh. This is correct for page routes — authenticated users need their tokens refreshed.

The problem: it was also running on /api/whatsapp/webhook. When Twilio POSTs an inbound message, there are no cookies in the request. The middleware ran anyway, attempted getUser(), got nothing back, and — depending on the Supabase SSR internals — either modified response headers or short-circuited the response before the route handler could return TwiML. Twilio received a malformed response and logged a delivery failure. Nothing in the Next.js logs looked wrong.

The fix was one addition to the middleware matcher config — a negative lookahead that excludes all api/ paths:

// middleware.ts — before
'/((?!_next/static|_next/image|favicon.ico|.*\.(?:svg|png|…)$).*)'

// middleware.ts — after
'/((?!_next/static|_next/image|favicon.ico|api/|.*\.(?:svg|png|…)$).*)'
//                                                  ^^^^

The principle applies beyond Supabase: any middleware that reads cookies, sets headers, or conditionally short-circuits a response should have an explicit exclusion list for stateless external-facing routes. Webhooks from Twilio, Meta, Stripe, GitHub — all of them arrive with no session context. They need a deterministic, unmodified response body. Middleware should never see them.

The check in code is cheap:

// Confirm your webhook is excluded before anything else
// GET https://your-domain.com/api/whatsapp/webhook
// Should return your handler's GET response, not a redirect or 401

2. Environment variables that only exist locally

We had a SKIP_TWILIO_VALIDATION=true guard in the webhook to bypass Twilio signature validation during local development:

if (process.env.SKIP_TWILIO_VALIDATION === 'true') {
  console.warn('Skipping Twilio signature validation (dev mode)');
  return true;
}

The intent was to set this only in .env.local so it would never reach production. But Vercel does not inherit .env.local — it only uses environment variables explicitly set in the Vercel dashboard or via vercel env. If you rely on .env.local as a "local only" gate, that gate only works if you never accidentally set the variable in Vercel.

The safer pattern: remove the env-var guard entirely. If you need to bypass validation for a debugging session, make the bypass explicit in source code with a prominent comment, and treat it as temporary diagnostic code to be reverted before the next commit:

// eslint-disable-next-line @typescript-eslint/no-unused-vars
function validateTwilioSignature(_req: NextRequest, _rawBody: string): boolean {
  // TEMPORARY: bypassed to diagnose URL mismatch. Revert after confirming endpoint.
  console.warn('[webhook] Signature validation bypassed');
  return true;
}

An inline comment in source is more visible during code review than an env var in a dashboard. It also forces an explicit decision — a comment with "TEMPORARY" in it doesn't accidentally stay in production unnoticed the way an environment variable can.