Clerk Webhook

Plainform includes a Clerk webhook at app/api/webhooks/clerk/route.ts. It listens for Clerk user events, verifies the webhook signature, and keeps the local Prisma User table in sync with Clerk.

Why It Exists

Clerk owns authentication state, but Plainform also needs a durable local user record for app data and payments. The Clerk webhook creates that bridge.

The webhook helps with:

• Subscriptions - Stripe checkout and subscription webhooks need a local user row to store stripeCustomerId, stripeSubscriptionId, plan data, and subscription status.
• User lifecycle sync - When a Clerk user is created, updated, or deleted, the local database follows the same lifecycle.
• Database relationships - Future app models can safely reference User.id, which is the Clerk user ID.

What The Webhook Handles

Plainform subscribes to these Clerk events:

• user.created - Upserts the user into the database with the primary email.
• user.updated - Upserts the user again so email changes are reflected locally.
• user.deleted - Deletes matching local user rows by Clerk user ID.

The handler verifies each request with verifyWebhook() and CLERK_WEBHOOK_SECRET before touching the database:

import { verifyWebhook } from '@clerk/nextjs/webhooks';
import { prisma } from '@/lib/prisma/prisma';
import { env } from '@/env';

export async function POST(req: NextRequest) {
  let event;

  try {
    event = await verifyWebhook(req, {
      signingSecret: env.CLERK_WEBHOOK_SECRET,
    });
  } catch (error) {
    return NextResponse.json(
      { message: 'Invalid webhook signature' },
      { status: 400 }
    );
  }

  switch (event.type) {
    case 'user.created':
      return await handleUserCreated(event.data);
    case 'user.updated':
      return await handleUserUpdated(event.data);
    case 'user.deleted':
      return await handleUserDeleted(event.data);
    default:
      return NextResponse.json({ message: 'Event type not handled' });
  }
}

Database Shape

The webhook writes to the User model in prisma/schema.prisma:

model User {
  id                           String    @id
  email                        String    @unique @db.VarChar(320)
  stripeCustomerId             String?   @unique
  stripeSubscriptionId         String?   @unique
  stripePriceId                String?
  subscriptionStatus           String?   @db.VarChar(64)
  subscriptionCurrentPeriodEnd DateTime?
  cancelAtPeriodEnd            Boolean   @default(false)
  planKey                      String?   @db.VarChar(128)
  createdAt                    DateTime  @default(now())
  updatedAt                    DateTime  @updatedAt

  @@index([subscriptionStatus])
}

Only id and email are written by the Clerk webhook. Stripe fields are filled later by checkout and Stripe subscription webhooks.

Setup

CLERK_WEBHOOK_SECRET="whsec_xxxxxxxxxxxxxxxxxxxx"

npm run dev

http://localhost:3000/api/webhooks/clerk

npx ngrok http 3000

ngrok http --url=your-static-domain.ngrok-free.app 3000

https://your-ngrok-domain.ngrok-free.app/api/webhooks/clerk

https://yourdomain.com/api/webhooks/clerk

npx prisma studio

How It Supports Payments

Subscriptions depend on this webhook because Stripe needs a local user record to update.

The flow is:

1. A user signs up with Clerk.
2. Clerk sends user.created to /api/webhooks/clerk.
3. Plainform creates or updates User { id, email }.
4. During checkout, Plainform creates or reuses a Stripe customer and stores stripeCustomerId on that user.
5. Stripe subscription webhooks update the same user row with subscription status, plan, period end, and cancellation state.

Without the Clerk webhook, a user may authenticate successfully but not exist in your database. That breaks subscription persistence because Stripe has nowhere reliable to write entitlement state.

Common Issues

Invalid Webhook Signature

Use the signing secret from the exact Clerk endpoint that is sending requests. If you create separate development and production endpoints, each has its own secret.

User Not Created Locally

Check that user.created is selected in the Clerk webhook event list, then inspect the Clerk delivery logs. If Clerk reports a 500, check your app logs and database connection.

ngrok URL Stopped Working

Free ngrok URLs usually change when the tunnel restarts. Update the Clerk webhook endpoint URL after restarting ngrok.

Missing Email

The handler uses the primary Clerk email when available and falls back to the first email address. If Clerk sends a user event without an email, Plainform returns 400 and logs the Clerk user ID.

Related Resources