eva: Skill for Claude Code

Webhooks

Output complete, working webhook handlers with verifyWebhook(req) verification in every handler.

When to Use Webhooks

Webhooks are asynchronous and eventually consistent. Delivery is fast but not guaranteed to be immediate, and may occasionally fail (Svix retries on a fixed schedule). Use them for:

• Database sync (a separate users / orgs table that follows Clerk)
• Notifications (welcome emails, Slack pings, internal alerts)
• Integrations triggered by lifecycle events

Do NOT rely on webhook delivery as part of a synchronous flow such as onboarding ("user signs up, then we read X from our DB"). For data the user just created, read it from the Clerk session token or call the Backend API directly. Webhooks fill the gap when you need data about other users or events the session token doesn't carry.

Verify Every Webhook

Use verifyWebhook(req) from the framework-specific package (@clerk/nextjs/webhooks, @clerk/express/webhooks, etc.). It reads CLERK_WEBHOOK_SIGNING_SECRET automatically and throws on bad signatures. Skipping verification, even for notification-only handlers, exposes the endpoint to spoofed events.

Make the Webhook Route Public

Webhook routes must be excluded from Clerk middleware protection. Without this, Clerk returns 401.

// proxy.ts (Next.js <=15: middleware.ts)
import { clerkMiddleware, createRouteMatcher } from "@clerk/nextjs/server";

const isPublicRoute = createRouteMatcher(["/api/webhooks(.*)"]);

export default clerkMiddleware(async (auth, req) => {
  if (!isPublicRoute(req)) await auth.protect();
});

Complete Webhook Handler (Next.js App Router)

// app/api/webhooks/route.ts
import { verifyWebhook } from "@clerk/nextjs/webhooks";
import { NextRequest } from "next/server";
import { db } from "@/lib/db";

export async function POST(req: NextRequest) {
  // ALWAYS verify - never skip, even for notification-only handlers
  let evt;
  try {
    evt = await verifyWebhook(req); // uses CLERK_WEBHOOK_SIGNING_SECRET automatically
  } catch (err) {
    console.error("Webhook verification failed:", err);
    return new Response("Verification failed", { status: 400 });
  }

  if (evt.type === "user.created") {
    const { id, email_addresses, first_name, last_name } = evt.data;
    const email = email_addresses[0]?.email_address;
    const name = `${first_name ?? ""} ${last_name ?? ""}`.trim();
    await db.users.create({ data: { clerkId: id, email, name } });
  }

  if (evt.type === "user.updated") {
    const { id, email_addresses, first_name, last_name } = evt.data;
    const email = email_addresses[0]?.email_address;
    await db.users.update({
      where: { clerkId: id },
      data: { email, first_name, last_name },
    });
  }

  if (evt.type === "user.deleted") {
    const { id } = evt.data;
    await db.users.delete({ where: { clerkId: id } });
  }

  if (evt.type === "organizationMembership.created") {
    const { organization, public_user_data, role } = evt.data;
    const orgId = organization.id;
    const userId = public_user_data.user_id;
    await db.teamMembers.create({ data: { orgId, userId, role } });
  }

  if (evt.type === "organizationMembership.deleted") {
    const { organization, public_user_data } = evt.data;
    const orgId = organization.id;
    const userId = public_user_data.user_id;
    await db.teamMembers.delete({ where: { orgId_userId: { orgId, userId } } });
  }

  return new Response("OK", { status: 200 });
}