Test Clerk webhooks locally

Receive Clerk events on your laptop while you build, with a URL Clerk can reach.

Before you beginCopy Anchor Link

• Node.js 18 or later
• A Horizon account and the CLI (see Getting started)
• A Clerk application with a Next.js App Router app using @clerk/nextjs

import { verifyWebhook } from '@clerk/nextjs/webhooks'
import { NextRequest } from 'next/server'

export async function POST(req: NextRequest) {
  try {
    const evt = await verifyWebhook(req)

    if (evt.type === 'user.created') {
      console.log('userId:', evt.data.id)
    }

    return new Response('Webhook received', { status: 200 })
  } catch (err) {
    console.error('Error verifying webhook:', err)
    return new Response('Error verifying webhook', { status: 400 })
  }
}

npm run dev

hrzn tunnel http://localhost:3000 -s my-app

CLERK_WEBHOOK_SIGNING_SECRET=whsec_123

Check it worksCopy Anchor Link

Send a test event from Clerk:

1. Open your endpoint in the Clerk Dashboard and select the Testing tab.
2. Select user.created in the dropdown.
3. Select Send Example.
4. Check that Status shows "Succeeded" under Message Attempts.

Horizon prints one line for the request:

  POST | [200] | /api/webhooks/clerk

Your dev server logs userId: followed by the ID from the example event.

TroubleshootingCopy Anchor Link

Horizon shows a non-200 status, or Clerk reports a failureCopy Anchor Link

Your Clerk middleware may block the route. Clerk sends events without a signed-in user, so the route must be public. Exclude /api/webhooks(.*) from any auth check in your middleware.

The handler logs "Error verifying webhook" and returns 400Copy Anchor Link

Check the signing secret first. It must match the one on your endpoint in the Clerk Dashboard, and your dev server must have restarted after you set CLERK_WEBHOOK_SIGNING_SECRET.

Events stop arriving after you restart the tunnelCopy Anchor Link

You started it without -s, so the subdomain changed. Restart with -s and the subdomain from your endpoint URL. To keep a subdomain yours across restarts, reserve it (see Pricing).

Clerk reports a 404Copy Anchor Link

The path in the endpoint URL must match your route: /api/webhooks/clerk.

Next stepsCopy Anchor Link

• Read Getting started for the full CLI setup.
• Read Clerk's guide on syncing data with webhooks to store users in your database.