Debug your webhooks

Developing with webhooks can be a new experience for developers. It can be hard to debug when something goes awry. This guide will cover the basics for debugging and help you to direct your attention to the correct spot.

Webhooks and local development

When you or a user of your application performs certain actions, a webhook can be triggered. You can see the full list of webhook events for a list of the actions that could result in a Webhook. Depending on the events subscribed to in the Webhooks⁠ page in the Clerk Dashboard, a webhook event will be triggered and sent to the specified endpoint in your application.

When you are developing on your localhost, your application is not internet facing and can't receive the webhook request. You will need to use a tool that creates a tunnel from the internet to your localhost. These tools will provide temporary or permanent URLs depending on the tool and the plan you subscribe to. Popular tools include ngrok, localtunnel and Cloudflare Tunnel.

This guide will address common issues that arise when developing with webhooks and how to debug them.

Check your Middleware configuration

Incoming webhook events will never be signed in -- they are coming from a source outside of your application. Since they will be in a signed out state, the route should be public.

The following example shows the recommended Middleware configuration for your webhook routes.

import { clerkMiddleware } from '@clerk/nextjs/server'

// Make sure that the `/api/webhooks/(.*)` route is not protected here
export default clerkMiddleware()

export const config = {
  matcher: [
    // Skip Next.js internals and all static files, unless found in search params
    '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
    // Always run for API routes
    '/(api|trpc)(.*)',
  ],
}

Test the Route Handler or API Route

If you are having trouble with your webhook, you can create a basic Route Handler and then test it locally. First, add the following file and code to your app.

If you're having trouble with your webhook, you can create a basic response and then test it locally.

1. Create a test route in your application:
   Next.js

   export async function POST() {
     return Response.json({ message: 'The route is working' })
   }

2. Run your application.
3. Run the following command to send a request to the test route:

   curl -H 'Content-Type: application/json' \
       -X POST http://localhost:3000/api/webhooks/test

If you see the {"message":"The route is working"}, then the basic Route Handler is working and ready to build on.

Check your configuration in the Clerk Dashboard

Whether you are developing locally or deploying to production, the webhook URL provided in your webhook endpoint⁠ must be exact and correct. The URL breaks down into three parts:

• the protocol (http vs https) - Whether in development using a tunnel or in production, the URL will almost always use https so ensure that the protocol is correct.
• the domain (domain.com) - The domain needs to be exact. A common error in production is not including the www.. Unlike entering a domain in your browser, a webhook will not be redirected from domain.com to www.domain.com. If your application lives on www.domain.com then the webhook URL must use that.
• the path (/api/webhooks/user) - The path must match the path in your application.

Debug your tunnel and webhook delivery

If your webhook is still getting errors after testing its route locally and verifying the endpoint's configuration in the Clerk Dashboard, you can further investigate the specific errors returned by the webhook. Depending on the type of error, your approach to fixing the webhook will vary.

1. In the Clerk Dashboard, navigate to the Webhooks⁠ page.
2. Select the endpoint for which you want to test.
3. In the Message attempts table, you will likely see that one or more of those attempts have failed. Select the failed attempt to expand it.
4. In the details for the attempt, there will be a HTTP RESPONSE CODE. The code will likely be either a 500 or a 4xx error, which will indicate there is some misconfiguration.

Common HTTP response codes

The following table has some of the common response codes you might see and what they indicate. This is not an exhaustive list and you may need to research the code or error you are receiving. See HTTP response status codes⁠ from MDN for reference.

Debug webhook verification

To verify the webhook, see the guide on webhooks for a detailed code example. You can also visit the Svix guide on verifying payloads⁠.

Diagnosing a problem in this part of the webhook can be challenging. Your best bet would be the liberal use of console.log. You could log out the following to check if the values are correct:

• the signing secret
• the headers
• the body before verifying
• the result of the .verify() attempt

The results of these will appear in the command line where you are running your application.

Checking the values and the progress of the webhook code will allow you to narrow down where the code is failing. They will often return null or errors where they should be returning values.

Check your logic

Once you have verified the webhook, you will now be writing your own code to handle the values from the webhook. This could range from saving data to a databse, or integrating with another system, to updating users or sending emails or SMS.

If the webhook is verified and you're seeing a 500 status code or your webhook is not behaving as expected, remember that you can use console.log to help diagnose what the problem is. Console logs and errors will be displayed on your command line, allowing you to see what's happening and address the bugs.