clerk-webhooks

clerk-webhooks

Webhooks

Prerequisite: Webhooks are asynchronous. Use for background tasks (sync, notifications), not synchronous flows.

Documentation Reference

Task Link

Overview https://clerk.com/docs/guides/development/webhooks/overview

Sync to database https://clerk.com/docs/guides/development/webhooks/syncing

Debugging https://clerk.com/docs/guides/development/webhooks/debugging

Event catalog https://dashboard.clerk.com/~/webhooks (Event Catalog tab)

Quick Start

• Create endpoint at app/api/webhooks/route.ts

• Use verifyWebhook(req) from @clerk/nextjs/webhooks

• Dashboard → Webhooks → Add Endpoint

• Set CLERK_WEBHOOK_SIGNING_SECRET in env

• Make route public (not protected by middleware)

Supported Events

User: user.created user.updated user.deleted

Organization: organization.created organization.updated organization.deleted

Organization Domain: organizationDomain.created organizationDomain.updated organizationDomain.deleted

Organization Invitation: organizationInvitation.created organizationInvitation.accepted organizationInvitation.revoked

Organization Membership: organizationMembership.created organizationMembership.updated organizationMembership.deleted

Roles: role.created role.updated role.deleted

Permissions: permission.created permission.updated permission.deleted

Session: session.created session.updated session.ended session.removed session.revoked session.pending

Communication: email.created sms.created

Invitations: invitation.created invitation.accepted invitation.revoked

Waitlist: waitlistEntry.created waitlistEntry.updated

Full catalog: Dashboard → Webhooks → Event Catalog

When to Sync

Do sync when:

• Need other users' data (social features, profiles)

• Storing extra custom fields (birthday, country, bio)

• Building notifications or integrations

Don't sync when:

• Only need current user data (use session token)

• No custom fields (Clerk has everything)

• Need immediate access (webhooks are eventual consistency)

Key Patterns

Make Route Public

Webhooks come unsigned. Route must be public:

Ensure clerkMiddleware() doesn't protect /api/webhooks(.*) path.

Verify Webhook

Use correct import and single parameter:

import { verifyWebhook } from '@clerk/nextjs/webhooks'
const evt = await verifyWebhook(req)  // Pass request directly

Type-Safe Events

Narrow to specific event:

if (evt.type === 'user.created') {
  // TypeScript knows evt.data structure
}

Handle All Three Events

Don't only listen to user.created. Also handle user.updated and user.deleted.

Queue Async Work

Return 200 immediately, queue long operations:

await queue.enqueue('process-webhook', evt)
return new Response('Received', { status: 200 })

Webhook Reliability

Retries: Svix retries failed webhooks for up to 3 days. Return 2xx to succeed, 4xx/5xx to retry.

Replay: Failed webhooks can be replayed from Dashboard.

Common Pitfalls

Symptom Cause Fix

Verification fails Wrong import or usage Use @clerk/nextjs/webhooks, pass req directly

Route not found (404) Wrong path Use /api/webhooks

Not authorized (401) Route is protected Make route public

No data in DB Async job pending Wait/check logs

Duplicate entries Only handling user.created Also handle user.updated

Timeouts Handler too slow Queue async work

Testing & Deployment

Local: Use ngrok to tunnel localhost:3000 to internet. Add ngrok URL to Dashboard endpoint.

Production: Update webhook endpoint URL to production domain. Copy signing secret to production env vars. Weekly Installs2.2KRepositoryclerk/skillsGitHub Stars27First SeenJan 30, 2026Security AuditsGen Agent Trust HubPassSocketPassSnykPassInstalled oncodex1.9Kopencode1.9Kgithub-copilot1.9Kgemini-cli1.9Kamp1.8Kkimi-cli1.8K