DEV Community: Gumbo Sveins

Polar sandbox vs live webhooks — why checkout works and entitlements do not

Gumbo Sveins — Sun, 13 Sep 2026 13:57:41 +0000

Polar sandbox vs live webhooks — why checkout works and entitlements do not

Checkout can succeed and your app can still treat the buyer as a free user. On Polar that usually means the webhook landed in the wrong world — sandbox secret on a live deploy, production endpoint still pointed at last night’s preview URL, or a signature check that never ran.

Article one covered the whole Next.js / Vercel go-live pass. This one is only Polar: sandbox vs production, and the webhook path that turns a paid order into an entitlement in your database.

Official Polar docs win when they disagree with anything here. Links below were fetched live from polar.sh/docs.

Polar does not have a Stripe-style “test mode”

Polar’s sandbox is a separate environment, not a toggle on your live org. From Sandbox Environment:

It's a dedicated server, completely isolated from the production instance…

Why? Polar is a Merchant of Record. They keep live money movements clean by isolating test data so it never interferes. You get unlimited sandbox accounts and orgs for experiments.

	Sandbox	Production
UI	sandbox.polar.sh	polar.sh
API	`https://sandbox-api.polar.sh/v1`	`https://api.polar.sh/v1`
Tokens	Minted in sandbox only	Minted in live org only
Products / customers / webhooks	Isolated	Isolated
Card for happy-path tests	Stripe test `4242 4242 4242 4242`	Real cards (or your live discounts)

API Overview is blunt: production tokens cannot talk to the sandbox API, and the reverse is also true. Create separate tokens in each environment.

Sandbox rate limits are lower (100 req/min vs 500 in production). That rarely bites a checkout flow; it does bite scripts that hammer the sandbox while you debug.

One sandbox limitation that surprises people (same sandbox doc): customer-facing emails in sandbox only go to members of your organization. Sub-addressing like you+test@example.com is accepted. Do not expect a random Gmail to get order confirmation mail from sandbox.

The four secrets that must travel together

Treat these as a matched set. Mixing any one row across worlds is how you get “checkout works, entitlement missing.”

Secret / ID	Preview & laptop	Production
`POLAR_ACCESS_TOKEN`	Token from sandbox.polar.sh	Token from the live org
`POLAR_SERVER` / SDK `server` or `environment`	`sandbox`	`production` (or omit — SDKs default to production)
`POLAR_WEBHOOK_SECRET`	Secret from the sandbox webhook endpoint	Secret from the live webhook endpoint
`POLAR_PRODUCT_ID`	Sandbox product UUID	Live product UUID

The official Next.js guide tells you to start on sandbox and later flip server: "sandbox" to "production" (Integrate Polar with Next.js). The Next adapter’s Checkout, CustomerPortal, and Webhooks helpers take the same idea (Next.js adapter).

Newer SDK previews use environment: "sandbox" on createPolar (API Overview). Older @polar-sh/nextjs examples use server: "sandbox". Either way: token origin must match the flag. A sandbox token with server: "production" fails in confusing 401s, not a clean error message.

Never prefix any of these with NEXT_PUBLIC_. Organization access tokens are server-only; Polar will revoke leaked OATs via secret scanning (API Overview).

Webhooks are the source of truth for entitlements

A success redirect proves the browser finished checkout. It does not prove your database granted access. Polar’s own Next.js guide frames webhooks as how you keep your DB in sync with checkouts, orders, and subscriptions (guide).

Minimum production shape with the official adapter:

// app/api/webhook/polar/route.ts
import { Webhooks } from "@polar-sh/nextjs";

export const POST = Webhooks({
  webhookSecret: process.env.POLAR_WEBHOOK_SECRET!,
  onOrderPaid: async (order) => {
    // Idempotent upsert: grant entitlement keyed by order.id
  },
  onCustomerStateChanged: async (customerState) => {
    // Mirror Polar's view of benefits / subscriptions
  },
});

Prefer granular handlers (onOrderPaid, onBenefitGrantCreated, …) over a giant onPayload switch once you know which events you subscribed to. The adapter documents the full list (Next.js adapter).

Register two endpoints, not one

Setup Webhooks walks the dashboard flow: Add Endpoint → absolute URL → Raw delivery → secret → event subscription.

Do that twice:

Sandbox org → tunnel or a long-lived staging URL while you develop.
Live org → https://your.domain/api/webhook/polar (stable custom domain).

Polar cannot reach localhost. For laptop work use either:

polar listen http://localhost:3000/ (Polar CLI tunnel — prints a forwarding secret; see Setup Webhooks), or
ngrok http 3000 / Cloudflare Tunnel and paste the https URL into the sandbox webhook (Next.js guide).

Never register the production webhook against a Vercel preview URL. Preview hostnames change every commit. Deliveries will 404 by Thursday while Polar still shows “checkout succeeded.”

Signature verification is non-negotiable

Polar signs payloads so you can reject forgeries. Handle & monitor webhook deliveries shows validateEvent from @polar-sh/sdk/webhooks (and the Python equivalent). The @polar-sh/nextjs Webhooks() helper does this for you when you pass webhookSecret.

Important timing note from Polar (as of docs fetched 13 Sep 2026):

Secrets generated on or after 8 September 2026, 00:00 UTC follow Standard Webhooks. Older secrets use Polar HMAC.

If you roll your own verification, read that page carefully — older secrets need different key handling than new whsec_… Standard Webhooks secrets. SDK versions 1.0.0-alpha.19+ try both. Prefer the official helper over hand-rolled HMAC.

Delivery rules that break entitlements in production

From the same delivery doc:

Rule	What it means for you
Timeout 10s (aim for <2s)	Ack fast; queue heavy work (grant email, CRM sync)
Retry up to 10× with backoff	Handlers must be idempotent — replay must not double-grant
10 consecutive failures → endpoint disabled	Org members get email; you must re-enable manually after fixing
No redirect following	`www` ↔ apex 301s count as failure. Point Polar at the final URL
Cloudflare Bot Fight Mode	Can 403 Polar even if you allowlist IPs — disable BFM or fix WAF
Auth middleware	Exclude `/api/webhook/polar` so Polar is not asked for a session

Also allowlist Polar’s egress IPs if your firewall requires it (list on the delivery page — Polar called out a new production IP 3.134.178.243).

A concrete failure timeline (and how to read the dashboard)

Monday: PR preview works. You register a sandbox webhook on https://my-app-git-feat-xyz.vercel.app/api/webhook/polar. Sandbox checkout → webhook → row in DB. Green.

Wednesday: You merge to main, set live POLAR_ACCESS_TOKEN, forget to create a live webhook (or you copy the preview URL into the live org). Customer pays on the custom domain. Polar shows a paid order. Your production DB never hears about it.

Thursday: Preview deployment from Monday is gone. Even the sandbox endpoint is 404ing. You look at Vercel Runtime Logs and see nothing. Polar’s webhook delivery page shows the red rows.

First move every time: Polar org (the one that took the money) → Settings → Webhooks → delivery history. You want recent 2xx. Then Vercel Runtime Logs for POST /api/webhook/polar. If Polar has 2xx and your DB is empty, the handler is wrong or not idempotent. If Polar has 404/403/3xx, fix the URL / middleware / Cloudflare before touching business logic.

Redeliver from the dashboard after you fix the route — Polar supports manual redelivery (delivery doc).

Go-live sequence for Polar only

Do this as its own checklist the evening you flip live payments — separate from “does the homepage render.”

Confirm you are logged into the live org on polar.sh (not sandbox.polar.sh).
Recreate products in live if you only built them in sandbox. Copy live product IDs into Production-scoped env — do not paste sandbox UUIDs.
Mint a live organization access token. Scope it Production-only in Vercel.
Set POLAR_SERVER=production (or remove server: "sandbox" / environment: "sandbox").
Add webhook https://your.domain/api/webhook/polar on the live org. Paste the new signing secret into Production POLAR_WEBHOOK_SECRET. Subscribe at least to order-paid / benefit-grant events you actually handle.
Set POLAR_SUCCESS_URL to the production origin with {CHECKOUT_ID}.
Redeploy so server env (and any bake-time public config) matches.
Run one live test: cheap product, 100% discount, or a payment you are willing to refund. Confirm: Polar delivery 2xx, Runtime Log line, entitlement row, customer portal sees the benefit.
Watch deliveries for 30 minutes. Keep Instant Rollback one click away.

Until that 2xx exists, do not post the buy link as “live.”

Soft sell (kit, not a live guarantee)

I packed the Polar scope cheat sheet, the full ~60-point launch checklist, five .env.example packs (including 02-polar.env.example), and a preview→prod runbook into a $19 download:

https://buy.polar.sh/polar_cl_uxzixqNM81nkPoIW3um9aacYzAmA1bXQbWqUe3EQE75

Checkout may still be enabling payments on Polar’s side — treat the link as the kit storefront once KYC / payouts are fully live, not as a promise that the card form works this second. Everything above still works as free reading tonight.

Educational material only. Re-read Polar’s sandbox, webhook setup, delivery, and Next.js guides before you take real money. Vendor names belong to their owners.

Ship Polar when sandbox checkout → webhook → entitlement already passed on a non-production URL, live products and secrets are Production-scoped, and the live webhook delivery page shows a recent 2xx for an order you caused on purpose.

The Next.js / Vercel production env mistakes that break launches

Gumbo Sveins — Sun, 13 Sep 2026 12:30:32 +0000

The Next.js / Vercel production env mistakes that break launches

You can ship a Next.js app that works on your laptop and still wake up to a broken production URL. The usual cause is not a bad feature — it is env scope, a sandbox token in the live org, or a webhook still pointed at last night’s preview hostname.

This is a go-live pass for solo engineers on the common 2026 stack: Next.js App Router, Vercel, Polar, Neon, Resend, Supabase. It is a human checklist, not an automated scan. Checking a box does not make the app secure. Official vendor docs win when they disagree with anything here.

I packed the full ~60-point version, five .env.example packs, and a preview→prod runbook into a $19 kit: https://buy.polar.sh/polar_cl_uxzixqNM81nkPoIW3um9aacYzAmA1bXQbWqUe3EQE75. Below is enough of the real material to run a serious launch review tonight, even if you never buy it.

The bug under most “it worked in preview” failures

Vercel gives you three worlds: Development, Preview, and Production. Mixing them is the most common launch bug.

Before you touch secrets, answer out loud: which Polar org, which database, and which Resend from address does each world use? If you cannot fill a cell, stop.

Also confirm:

The production branch in Vercel is the branch you think it is (main unless you changed it).
Preview deployments are on, and a PR URL is not the production hostname.
You will not register the production Polar webhook against a changing preview URL.

Ten checks that catch real production outages

These are lifted from the full checklist. Work them top to bottom on a copy you own.

Secrets and Vercel scopes

4. .env, .env.local, .env.production, and .env*.local are in .gitignore. git ls-files | grep env should return nothing useful to an attacker.

5. No secret is prefixed NEXT_PUBLIC_. That prefix inlines the value into the browser bundle. Tokens, service-role keys, webhook secrets, and database URLs never get it.

6. Every variable in the Vercel dashboard has an explicit scope: Production, Preview, Development. “Apply to all” is only for non-secret public config.

7. Production Polar tokens, production database URLs, and the live Resend key are scoped Production only. Preview gets its own sandbox / branch values.

9. AUTH_SECRET / NEXTAUTH_SECRET is at least 32 bytes (openssl rand -base64 32) and different in preview and production.

10. NEXT_PUBLIC_APP_URL (and AUTH_URL / NEXTAUTH_URL if you use Auth.js) equals the origin of that environment. No leftover *.vercel.app in production.

11. NEXT_PUBLIC_* is baked at next build. Changing the dashboard value does nothing until you redeploy.

Auth (one that people skip)

16. Every Server Action and Route Handler that mutates data re-checks the session inside the function. A layout or proxy check is not enough.

World	Git	Polar	Database	Email
Development	laptop	sandbox	local or a personal Neon/Supabase branch	Resend test addresses
Preview	every PR	sandbox	disposable Neon branch or staging Supabase	Resend test addresses — never real customers
Production	`main`	live org + live products	production Neon / Supabase	verified domain

Billing, database, email (the three that usually explode on day one)

22. Polar: POLAR_SERVER / server: in the SDK matches the token. A sandbox token with server: "production" fails in confusing ways. Sandbox and production are different servers, different tokens, different products, different webhook secrets.

25. The production webhook endpoint is an absolute public URL Polar can reach — not localhost, not a PR preview URL. Signature is verified with POLAR_WEBHOOK_SECRET. Preview URLs change every commit; deliveries will 404 by Thursday.

29. Neon: the app uses the pooled connection string (-pooler. host). Migrations use the direct / unpooled string. Using the direct URL as the runtime URL on Vercel Functions is how you get too many connections.

36. Resend: production from uses a domain you verified at resend.com/domains. onboarding@resend.dev is test-only and must not ship.

40. Preview and local send only to Resend test addresses (delivered@resend.dev, bounced@resend.dev) or your own inbox. Preview must not email real users.

Supabase (if you use it)

44. RLS is enabled on every table in public that the Data API can see. A table with RLS off is public to anyone holding the anon / publishable key.

Three env pitfalls from the actual packs

These comments live in the kit’s .env.example files because they keep biting people.

1. `NEXT_PUBLIC_APP_URL` without a redeploy

From the Next/Vercel pack: the value is inlined at build time. After you change it in Vercel you must redeploy. Editing the variable alone does not patch an already-built bundle. Same rule for any other NEXT_PUBLIC_* key.

Symptom from the runbook: build OK, runtime undefined env — or auth looping on the custom domain because AUTH_URL is still *.vercel.app. Fix: set the production origin, redeploy, clear cookies.

2. Polar sandbox token in production (or the reverse)

From the Polar pack: mint the token in the same environment you will call. Preview / Development → token from sandbox.polar.sh. Production token from the live organization. POLAR_SERVER must be sandbox or production to match.

Also: sandbox product IDs are invalid in production. Copy IDs from the dashboard of the matching org. Production webhook must be your custom domain, not a PR preview URL.

3. Neon pooled vs direct on Vercel

From the Neon pack:

DATABASE_URL — pooled (-pooler. host) → Server Components, Route Handlers, Server Actions
DATABASE_URL_UNPOOLED — direct → migrations only (prisma migrate deploy, drizzle-kit migrate)

Never use the unpooled string as the runtime URL on Vercel Functions. Always keep sslmode=require. Confirm that Production still points at the main branch, not a leftover preview branch from the Vercel + Neon integration.

Bonus Resend trap, same class of mistake: shipping with EMAIL_FROM=…<onboarding@resend.dev>. Development and Preview can keep that; Production needs Name <you@verified-domain> and a new deploy after you change it.

Preview → production in one sitting

Do not interleave “I’ll fix env later” with a git push to main.

laptop  --push PR-->  Preview URL  --merge main-->  Production URL
   |                      |                              |
 sandbox Polar        sandbox Polar                 live Polar
 Neon branch          Neon branch                   Neon main
 Resend test          Resend test                   verified domain

Preview first. Fill Preview-scoped secrets (sandbox Polar, Neon branch, Resend test recipients, staging Supabase). Pull env locally, run next build && next start, open a PR, smoke-test auth / a write / a sandbox checkout / a test email on the preview URL. Merge only when that is green.

Production values before the merge. Production scope only for live Polar token + webhook secret, POLAR_SERVER=production, pooled + unpooled Neon main URLs, live Resend key + verified EMAIL_FROM, production Supabase project keys, and a new AUTH_SECRET. Mark tokens Sensitive. Do not tick Preview on those rows.

Attach domain and webhook. Certificate valid → Polar live webhook on https://your.domain/api/webhook/polar Resend domain verified with one real message to yourself → run migrations against DATABASE_URL_UNPOOLED → then ship main.

Immediately after deploy: private window, home / sign-up / sign-in / sign-out, one write path, one Polar live test (or 100% discount) with webhook row + entitlement confirmed, one email from the verified domain, custom domain + HTTPS + www/apex, and a 30-minute log watch before you post the URL. Keep the previous production deploy one click away for Instant Rollback. If you migrated the database forward, do not promote an old deploy until you have a down migration or a restore point.

When something is already on fire

Symptom	Likely cause	First move
Build OK, runtime `undefined` env	Scoped to Preview only, or `NEXT_PUBLIC_*` changed without redeploy	Check scope → redeploy
Polar 401 / empty webhook	Sandbox token in production, or `server` mismatch	Compare token origin to `POLAR_SERVER`

DEV Community: Gumbo Sveins

Polar sandbox vs live webhooks — why checkout works and entitlements do not

Polar sandbox vs live webhooks — why checkout works and entitlements do not

Polar does not have a Stripe-style “test mode”

The four secrets that must travel together

Webhooks are the source of truth for entitlements

Register two endpoints, not one

Signature verification is non-negotiable

Delivery rules that break entitlements in production

A concrete failure timeline (and how to read the dashboard)

Go-live sequence for Polar only

Soft sell (kit, not a live guarantee)

The Next.js / Vercel production env mistakes that break launches

The Next.js / Vercel production env mistakes that break launches

The bug under most “it worked in preview” failures

Ten checks that catch real production outages

Secrets and Vercel scopes

Auth (one that people skip)

Billing, database, email (the three that usually explode on day one)

Supabase (if you use it)

Three env pitfalls from the actual packs

1. NEXT_PUBLIC_APP_URL without a redeploy

2. Polar sandbox token in production (or the reverse)

3. Neon pooled vs direct on Vercel

Preview → production in one sitting

When something is already on fire

1. `NEXT_PUBLIC_APP_URL` without a redeploy