Syncing Stripe Customers with Clerk Users Using Clerk Webhooks & Next.js

This guide demonstrates how to synchronize your Stripe customers with your Clerk users using webhooks. When a user is created or deleted in Clerk, the integration automatically creates or removes the corresponding Stripe customer. This example uses a Next.js application and leverages Svix for secure webhook signature verification.

Overview

The integration works as follows:

• User Created: When a new Clerk user is registered, a webhook event (user.created) triggers:

  • Retrieval of full user details from Clerk.

  • Creation of a Stripe customer using the user’s email.

  • Storage of the Stripe customer ID in the Clerk user’s public metadata.

• User Deleted: When a Clerk user is removed, a webhook event (user.deleted) triggers:

  • A lookup for the Stripe customer based on the Clerk user ID stored in the customer's metadata.

  • Deletion of the corresponding Stripe customer.

Key Components:

• Clerk Webhook Integration: Follow Clerk’s Sync Data Documentation.

• Next.js: Hosts the webhook endpoint.

• Svix: Verifies incoming webhook requests.

• Stripe API: Manages customer creation and deletion.

Prerequisites

Before implementing the integration, ensure you have:

• A Next.js project set up.

• A Clerk account with webhook access.

• A Stripe account with API keys.

• Environment variables configured for your secrets.

1. Initializing Stripe

Create a file (e.g., lib/stripe.js) to initialize and export your Stripe instance:

import Stripe from 'stripe';

export const _stripe = new Stripe(process.env.STRIPE_SECRET_KEY, {
  apiVersion: '2025-01-27.acacia', // Use the appropriate API version for your project
});

Tips:

• Ensure your .env file includes STRIPE_SECRET_KEY.

• Use this centralized instance throughout your project for consistency.

2. Implementing the Webhook Endpoint in Next.js

The webhook endpoint listens for events from Clerk and uses Svix to verify the authenticity of requests. Create your endpoint (for example, at pages/api/webhook.js):

import { Webhook } from "svix";
import { headers } from "next/headers";
import { clerkClient } from "@clerk/nextjs/server";
import { _stripe } from "@/lib/stripe";

export async function POST(req) {
  const SIGNING_SECRET = process.env.SIGNING_SECRET;
  if (!SIGNING_SECRET) throw new Error("Missing SIGNING_SECRET");

  const wh = new Webhook(SIGNING_SECRET);
  const headerPayload = await headers();
  const svix_id = headerPayload.get("svix-id");
  const svix_timestamp = headerPayload.get("svix-timestamp");
  const svix_signature = headerPayload.get("svix-signature");

  if (!svix_id || !svix_timestamp || !svix_signature) {
    return new Response("Missing Svix headers", { status: 400 });
  }

  const payload = await req.json();
  const body = JSON.stringify(payload);

  let evt;
  try {
    evt = wh.verify(body, {
      "svix-id": svix_id,
      "svix-timestamp": svix_timestamp,
      "svix-signature": svix_signature,
    });
  } catch (err) {
    // Optionally log the error for debugging
    return new Response("Verification error", { status: 400 });
  }

  if (evt.type === "user.created") 
    return await handleUserCreated(evt.data);
  if (evt.type === "user.deleted") 
    return await handleUserDeleted(evt.data);

  return new Response("Event not processed", { status: 200 });
}

Key Points:

• Header Verification: Svix checks the svix-id, svix-timestamp, and svix-signature headers to ensure the request’s authenticity.

• Error Handling: Returns meaningful responses for missing headers or verification failures.

• Event Routing: Directs events to the appropriate handler based on the event type.

3. Handling User Creation

When a new Clerk user is created, this function:

1. Retrieves the complete user profile from Clerk.

2. Creates a new Stripe customer using the user's email.

3. Updates the Clerk user's metadata with the new Stripe customer ID.

async function handleUserCreated(data) {
  // Fetch full user details from Clerk
  const user = await clerkClient.users.getUser(data.id);
  const email = user.primaryEmailAddress?.emailAddress;
  if (!email) {
    return new Response("No email found", { status: 400 });
  }

  try {
    // Create a Stripe customer using the email and store the Clerk user ID in metadata
    const stripeCustomer = await _stripe.customers.create({
      email,
      metadata: { clerkUserId: data.id },
    });

    // Update Clerk user metadata with the Stripe customer ID for future reference
    await clerkClient.users.updateUserMetadata(data.id, {
      publicMetadata: { stripeCustomerId: stripeCustomer.id },
    });
  } catch (error) {
    // Optionally log the error details here
    return new Response("Stripe customer creation failed", { status: 500 });
  }

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

Key Points:

• Data Consistency: Ensures that each Clerk user is linked to a corresponding Stripe customer.

• Metadata Storage: Saves the Stripe customer ID in Clerk for easy reference during deletion or updates.

4. Handling User Deletion

When a Clerk user is deleted, this function:

1. Searches for the associated Stripe customer using the stored Clerk user ID.

2. Deletes the Stripe customer if found.

async function handleUserDeleted(data) {
  if (!data.id) return new Response("No Clerk user ID", { status: 200 });

  try {
    // Search for the Stripe customer by matching the clerkUserId metadata
    const searchResult = await _stripe.customers.search({
      query: `metadata['clerkUserId']:'${data.id}'`,
    });

    // If the customer exists, delete it from Stripe
    if (searchResult.data.length) {
      await _stripe.customers.del(searchResult.data[0].id);
    }
  } catch (error) {
    // Optionally log error details here
    return new Response("Stripe customer deletion failed", { status: 500 });
  }

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

Key Points:

• Customer Lookup: Uses Stripe’s search API to locate the customer using the Clerk user ID stored in metadata.

• Graceful Deletion: Ensures that the deletion process does not cause errors if the customer is not found.

5. Environment Variables Setup

Ensure your .env file contains the necessary environment variables:

SIGNING_SECRET=your_svix_signing_secret
STRIPE_SECRET_KEY=your_stripe_secret_key

Note: These secrets are critical for authenticating webhook requests and interacting securely with the Stripe API.

6. Testing the Webhook

Before deploying your integration, thoroughly test your webhook:

Testing with Clerk

• Dashboard: Navigate to the Clerk Dashboard → Webhooks.

• Simulate Events: Trigger test events such as user.created and user.deleted to simulate actual scenarios.

Testing with Stripe

• Dashboard: Log into the Stripe Dashboard.

• Verify Changes: Confirm that the corresponding Stripe customer records are created or deleted as expected when you simulate Clerk events.

Conclusion

By following this guide, you can achieve seamless synchronization between your Clerk user management and Stripe’s customer handling. This integration ensures that whenever a Clerk user is created or deleted, your billing system remains up to date.