clerk-webhooks

SKILL.md

Webhooks

Output complete, working webhook handlers with verifyWebhook(req) verification in every handler.

When to Use Webhooks

Webhooks are asynchronous and eventually consistent. Delivery is fast but not guaranteed to be immediate, and may occasionally fail (Svix retries on a fixed schedule). Use them for:

Database sync (a separate users / orgs table that follows Clerk)

Notifications (welcome emails, Slack pings, internal alerts)

Integrations triggered by lifecycle events

Do NOT rely on webhook delivery as part of a synchronous flow such as onboarding ("user signs up, then we read X from our DB"). For data the user just created, read it from the Clerk session token or call the Backend API directly. Webhooks fill the gap when you need data about other users or events the session token doesn't carry.

Verify Every Webhook

Use verifyWebhook(req) from the framework-specific package (@clerk/nextjs/webhooks, @clerk/express/webhooks, etc.). It reads CLERK_WEBHOOK_SIGNING_SECRET automatically and throws on bad signatures. Skipping verification, even for notification-only handlers, exposes the endpoint to spoofed events.

Make the Webhook Route Public