Clerk has updated our SDK to support Next.js version 13.4.0. We've added stable support for the App Router, which is the default for new applications. We've also improved the ergonomics of our middleware helper for more composability and to mitigate common pitfalls.

See the updates in our new Next.js documentation

Next.js version 13.4.0 launched today and the App Router is now stable. In turn, Clerk's support for the App Router is also now stable in 

 helpers have been moved to a permanent home in 

 are no longer necessary, and you can import from 

 intstead. The package now automatically detects if components are being used from a client component or a server component, and loads the proper form.

That's all! Our documentation has been updated to 

Along with today's launch, we've also released a new middleware helper to make things a little easier and more composable.

In its simplest form, these few lines are all you need to 

This sets your application in a protected mode – if users are signed  out the will be automatically redirected to a sign in. Unprotected pages need to be explicitly listed in the 

 arguments to enable more composability with libraries like 

.  For more details, checkout the updated 

Stable Support for the Next.js App Router, plus a Middleware Update!

🔑 Prefill Sign Up & Sign In Components

You are now able to prefill email address, username, and phone numbers in the 

 components, either by passing an initialValues prop or by using query strings. Check out 

Users who exist in your account before you enable SAML can now authenticate with your IdP and link an enterprise connection to their account.

 package introduces stable support for Remix v2, without the need for the 

 prefixes of “future-flags”. Since this is a breaking change, a major bump was needed (v3) – to get the latest version, use 

Updated Email Blocking so that blocking an email address will also block all its subaddresses

 for the file-system-based router that was introduced with Expo Router v2

Auth with Clerk, tRPC, and Cloudflare Workers

 explains how to integrate Clerk authentication into a tRPC API running on Cloudflare Workers.

: This YouTube video demonstrates building an LMS platform like Udemy using Next.js, React, Stripe, Clerk, Mux, and Planetscale.

How to Build a SaaS Product with Next.js, Clerk, AWS DynamoDB & Stripe

: This article shows how to build a complete SaaS product from start to finish using Next.js App Router, AWS DynamoDB, Clerk for authentication, and Stripe for payments.

: Learn how to get started with webhooks to build integrations in a Next.js application with Clerk's fully-featured authentication.

 on their recent raise, and for updating the OAuth flow for 

, an open source platform for storing and displaying the certifications you receive, which uses Clerk for auth. Thank you for helping people organize and increase the visibility of their certificates!

, a new project that is using AI to demystify renters’ rights in NYC, for preventing many headaches, and for leveraging Clerk.

Stay tuned for future updates. If you have feedback or suggestions tweet us at 

Changelog September 29, 2023

In an age of software that is composed of decoupled services built by specialized (often outsourced) teams, webhooks play an important architectural role. Webhooks enable us to outsource important user interactions and services to external platforms that are specifically designed for those purposes, and still have our applications be able to respond to those interactions.

For example, Clerk is specifically designed to handle authentication and user management related interactions on behalf of your applications. Webhooks allow Clerk to notify your application of these interactions so that you can implement custom follow-up logic. These interactions include (but are not limited to) signing in, changing profile information, creating an organization, or getting invited to an organization. Clerk ensures that all these important interactions are handled securely and responsively, while giving you a way to implement follow-up logic.

In this blog post we will build a simple webhook integration in a Next.js project. We will also explore the use cases of webhooks with Clerk and discuss how to best handle webhooks for production-ready applications.

This post assumes basic familiarity with Next.js and Clerk.

For this walkthrough we will start with a Next.js project that is already setup with Clerk. However, you can create a webhook subscription in any server-side web framework like Express or Fastify.

If you don’t already have a Next.js project setup with Clerk, you can start by cloning the Clerk Next.js App Router template.

This will create a minimal Next.js project fully setup with Clerk’s embedded components and a secured dashboard page.

 file in the root of the project and add your keys here from the Clerk dashboard.

Let’s create an API route that will handle the Clerk webhook. This handler will live in 

Webhooks are POST requests by default, so let’s create a handler for receiving POST requests.

The webhook event data is available as the request payload. Let’s parse it out and log it to the console.

 type for strong typescript inference. For now we will simply assert the webhook payload to be of this type.

Let’s also create a simple GET handler to test if we can access this URL.

Add this endpoint as a public route to the Clerk middleware

Now we can navigate to this endpoint in the browser.

That’s all we need to setup a simple webhook endpoint! Now we can provide Clerk with a URL to this endpoint, and we can start receiving events.

However, we are not ready to test this locally yet. While the application is accessible on 

 in our machine, it’s not accessible to anything outside our local network. Since webhook requests are originated from Clerk’s servers, the 

 URL will just point back to the Clerk server instead of our machine.

While we could provide Clerk with the public IP address of our machine, any incoming requests to our local home/work networks will be blocked by firewalls.

To work around this problem, we can use a tunneling service like 

, which creates a secure tunnel to our local machine from the cloud.

Let’s setup localtunnel in a new terminal window.

Once the installation is complete, we can create a tunnel to our local server.

You should see an output in your terminal like this.

Localtunnel will generate a random URL on the 

 domain that will point to your locally running server on port 3000. We can navigate to this new URL in our browser.

Localtunnel has a security mechanism built in to prevent abuse from malicious actors and phishing links. It asks for the public IP address of your local machine to ensure that it’s really you trying to access your application. Follow the instructions on this page to get your public IP address, and submit it on this page.

Once that’s done, we can access our application on this URL. We should also be able to access our webhook endpoint.

If the application doesn’t show up, make sure both the nextjs server and localtunnel are running on separate terminal windows.

Now we are ready to plug our endpoint into Clerk’s dashboard. Go to the Webhooks page, and click Add Endpoint. Enter the localtunnel URL here. You can also add a description for this endpoint.

Here you can select which specific events you want to receive at this endpoint. Let’s leave these unselected for now so that we can receive webhooks for all events. Hit Create.

Once the webhook endpoint is created, we can navigate to the Testing tab. Here we can trigger an example event manually to test our webhook endpoint. Select any event from the dropdown, and hit Send Example.

If your application is running locally and tunneling is set up correctly, you should see a message in your console with the example event.

You will also see a log entry in the Testing tab that shows the status of the webhook.

Even though the webhook was correctly received and logged to the console, the dashboard marks the webhook delivery as failed. To ensure that the delivery is marked as succeeded, we need to return a success response from our endpoint.

Let’s send another example event. This time it the webhook should be marked as succeeded.

Now we can test the webhook with real events. Navigate to your application and sign up with a new account. This should log two webhook events in the console - a 

Congratulations, we now have a functioning webhook receiver in our application! We can now further explore what events are triggered by Clerk. For example,

Remotely signing out a different device will result in a 

Creating a new organization will trigger an 

We can also see logs for real webhook events in the dashboard.

When you deploy this app to a cloud environment like Vercel, you will need to create a new endpoint in the Clerk dashboard that points to the deployed application instead of a localtunnel URL.

Note that localtunnel will generate a random URL everytime we start the tunnel, which means everytime we are testing with webhooks locally, we will need to create a new endpoint in the Clerk dashboard. To solve this, we can ask localtunnel to provision a specific URL by adding a 

If the requested URL is available, it will be provisioned for us instead of a randomly generated URL. This will allow us to reuse the same endpoint in the Clerk dashboard everytime we are testing locally.

So now that we are receiving webhook events from Clerk, what can we do with it?

While Clerk’s own database acts as the primary source of truth for authentication and user management, you can create a copy of this data in your own database which gets updated asynchronously through webhooks. This allows you to query your own database for user data instead of relying on Clerk’s APIs, along with flexibility with the data model, complex queries, transactional guarantees, and real time behavior. This mechanism is called 

Some advanced use cases might rely on asynchronous workflows and background jobs, such as sending notifications to users or other external systems. These workflows can be triggered to execute when a webhook event is received, for example, sending new users an onboarding email to your application, or subscribing them to mailing lists for software updates and promotional campaigns. Such systems are called 

Clerk allows you to bring your own Email and/or SMS servers for delivering auth-related messages which would usually be delivered by Clerk. Whenever an auth-related message is created, Clerk sends a webhook event with that message to your application. You can configure Clerk to not deliver these messages in the Clerk dashboard, and instead handle the delivery yourself by listening to the webhook events. (add links to HWR and docs)

We will walk through implementing some of these use-cases in future articles.

While setting up a simple webhook receiver for testing purposes is straightforward, operating a webhook-driven system in production requires some additional work. Clerk implements webhook deliveries through 

, a service that specializes in handling webhook deliveries. Svix manages concerns like scalability, logging, retries, security, and delivery guarantees. However, we still need to ensure that our application is setup to receive and process webhooks correctly. Let’s explore some best practices for implementing webhook endpoints for production-ready applications.

Webhook deliveries are marked as successful or failed depending on the HTTP response returned by our webhook endpoint. A failed webhook delivery is retried with exponential backoff until it succeeds, ensuring that our application will never miss an event. The exponential backoff ensures that our application servers are not overloaded with retries and explode server resources.

Our webhook endpoints should be setup to return a successful response (20x) if everything went well. But in case of an error during the processing of a webhook, we can simply throw an error response (40x or 50x) and expect a retry, which often succeeds. We can also monitor the webhook status in the Clerk dashboard, which provides observability into failed webhook deliveries and help discover issues.

Since webhooks requests can originate on any remote server, webhook endpoints are vulnerable to attacks from malicious actors. Securing webhook endpoints is important to ensure malicious actors cannot make unwanted changes to your application.

Svix adds security measures to webhook requests by adding a secure hash in the request headers created using a secret key. We can use the 

 library in our webhook endpoint to validate that the request was sent by a legitimate Svix server and not a malicious actor.

We can get the webhook signing secret from the Clerk dashboard and store in a 

Now our webhook endpoint is fully secure and ready to be deployed to production servers.

In our walkthrough, we configured Clerk to trigger the webhook endpoint for all events. While this was useful for testing, we want to minimize the use of server resources by only processing events that we actually care about.

For production endpoints, we can apply event filters in the Clerk dashboard by selecting the events that we are processing in the application, and leaving everything else unselected.

Webhooks play an important role in creating unified user experiences through integrations like data sync and event driven systems. In this article we setup a simple webhook endpoint, explored some use cases, and addressed concerns like security and error handling.

We will dive deep into specific use cases around data sync and event driven systems in future blog posts and walk through implementing them into our projects.

, or to learn more about the webhook events exposed by Clerk, 

Need help?

Engineering

Engineering

Stable Support for the Next.js App Router, plus a Middleware Update!

@clerk/nextjs@4.17.0 is released

Stable App Router Support

Middleware Update

Start now,
no strings attached

Pricing built for
businesses of all sizes.

Newsletter!

Engineering

Engineering

Stable Support for the Next.js App Router, plus a Middleware Update!

Stable App Router Support

Middleware Update

Start now,no strings attached

Pricing built for.css-qa8l2m{color:var(--chakra-colors-primary-500);}businesses of all sizes.

Newsletter!

Start now,
no strings attached

Pricing built for
businesses of all sizes.