[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7A51QATSBPCDZVP2BGTG4FW":3,"skill-same:01M7A51QATSBPCDZVP2BGTG4FW":58},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":27,"commitSha":28,"skillDirectory":29,"forksCount":14,"repositoryHtmlUrl":30,"repositoryHomepageUrl":6,"ownerHtmlUrl":31,"ownerBlogUrl":6,"ownerDescription":32,"updatedAt":33,"install":34,"resources":47},"01M7A51QATSBPCDZVP2BGTG4FW","clerk-webhooks",null,"Clerk webhooks for real-time events and data syncing. Verify with verifyWebhook from the framework-specific package. Handle user, session, organization, billing, and payment events. Build event-driven features like database sync, notifications, and integrations.","NeelakshSaxena\u002FVayu","NeelakshSaxena","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F87892838?v=4","01M7A3B9YFS6F6N9DD1787DT86","Neelaksh Saxena","01M7A3B9ZKBT09MNMPX2XN69BY",0,"MIT","https:\u002F\u002Fgithub.com\u002FNeelakshSaxena\u002FVayu\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fclerk-webhooks\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\ndescription: \"Clerk webhooks for real-time events and data syncing. Verify with verifyWebhook from the framework-specific package. Handle user, session, organization, billing, and payment events. Build event-driven features like database sync, notifications, and integrations.\"\nlicense: \"MIT\"\nmetadata: {\"author\":\"clerk\",\"version\":\"1.2.0\"}\n---\n# Webhooks\n\nOutput complete, working webhook handlers with `verifyWebhook(req)` verification in every handler.\n\n## When to Use Webhooks\n\nWebhooks 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:\n\n- Database sync (a separate users \u002F orgs table that follows Clerk)\n- Notifications (welcome emails, Slack pings, internal alerts)\n- Integrations triggered by lifecycle events\n\nDo 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](https:\u002F\u002Fclerk.com\u002Fdocs\u002Fguides\u002Fsessions\u002Fsession-tokens) 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.\n\n## Verify Every Webhook\n\nUse `verifyWebhook(req)` from the framework-specific package (`@clerk\u002Fnextjs\u002Fwebhooks`, `@clerk\u002Fexpress\u002Fwebhooks`, 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.\n\n## Make the Webhook Route Public\n\nWebhook routes must be excluded from Clerk middleware protection. Without this, Clerk returns 401.\n\n```typescript\n\u002F\u002F proxy.ts (Next.js \u003C=15: middleware.ts)\nimport { clerkMiddleware, createRouteMatcher } from '@clerk\u002Fnextjs\u002Fserver'\n\nconst isPublicRoute = createRouteMatcher(['\u002Fapi\u002Fwebhooks(.*)'])\n\nexport default clerkMiddleware(async (auth, req) => {\n  if (!isPublicRoute(req)) await auth.protect()\n})\n```\n\n## Complete Webhook Handler (Next.js App Router)\n\n```typescript\n\u002F\u002F app\u002Fapi\u002Fwebhooks\u002Froute.ts\nimport { verifyWebhook } from '@clerk\u002Fnextjs\u002Fwebhooks'\nimport { NextRequest } from 'next\u002Fserver'\nimport { db } from '@\u002Flib\u002Fdb'\n\nexport async function POST(req: NextRequest) {\n  \u002F\u002F ALWAYS verify - never skip, even for notification-only handlers\n  let evt\n  try {\n    evt = await verifyWebhook(req) \u002F\u002F uses CLERK_WEBHOOK_SIGNING_SECRET automatically\n  } catch (err) {\n    console.error('Webhook verification failed:', err)\n    return new Response('Verification failed', { status: 400 })\n  }\n\n  if (evt.type === 'user.created') {\n    const { id, email_addresses, first_name, last_name } = evt.data\n    const email = email_addresses[0]?.email_address\n    const name = `${first_name ?? ''} ${last_name ?? ''}`.trim()\n    await db.users.create({ data: { clerkId: id, email, name } })\n  }\n\n  if (evt.type === 'user.updated') {\n    const { id, email_addresses, first_name, last_name } = evt.data\n    const email = email_addresses[0]?.email_address\n    await db.users.update({ where: { clerkId: id }, data: { email, first_name, last_name } })\n  }\n\n  if (evt.type === 'user.deleted') {\n    const { id } = evt.data\n    await db.users.delete({ where: { clerkId: id } })\n  }\n\n  if (evt.type === 'organizationMembership.created') {\n    const { organization, public_user_data, role } = evt.data\n    const orgId = organization.id\n    const userId = public_user_data.user_id\n    await db.teamMembers.create({ data: { orgId, userId, role } })\n  }\n\n  if (evt.type === 'organizationMembership.deleted') {\n    const { organization, public_user_data } = evt.data\n    const orgId = organization.id\n    const userId = public_user_data.user_id\n    await db.teamMembers.delete({ where: { orgId_userId: { orgId, userId } } })\n  }\n\n  return new Response('OK', { status: 200 })\n}\n```\n\n## Full Example: Welcome Email (Resend) + Slack Notification on user.created\n\nNotification-only handlers still verify the signature. Same pattern as the database-sync handler:\n\n```typescript\n\u002F\u002F app\u002Fapi\u002Fwebhooks\u002Froute.ts\nimport { verifyWebhook } from '@clerk\u002Fnextjs\u002Fwebhooks'\nimport { NextRequest } from 'next\u002Fserver'\nimport { Resend } from 'resend'\n\nconst resend = new Resend(process.env.RESEND_API_KEY)\n\nexport async function POST(req: NextRequest) {\n  \u002F\u002F Step 1: ALWAYS verify the webhook signature - NEVER skip this\n  let evt\n  try {\n    evt = await verifyWebhook(req) \u002F\u002F uses CLERK_WEBHOOK_SIGNING_SECRET env var\n  } catch (err) {\n    console.error('Webhook verification failed:', err)\n    return new Response('Verification failed', { status: 400 })\n  }\n\n  \u002F\u002F Step 2: Listen for user.created event\n  if (evt.type === 'user.created') {\n    \u002F\u002F Step 3: Extract user email and name from webhook payload\n    const { id, email_addresses, first_name, last_name } = evt.data\n    const email = email_addresses[0]?.email_address\n    const name = `${first_name ?? ''} ${last_name ?? ''}`.trim()\n\n    \u002F\u002F Step 4: Call Resend API to send welcome email\n    await resend.emails.send({\n      from: 'noreply@yourdomain.com',\n      to: email,\n      subject: 'Welcome!',\n      html: `\u003Cp>Hi ${name}, welcome to our app!\u003C\u002Fp>`,\n    })\n\n    \u002F\u002F Step 5: Post notification to Slack channel\n    await fetch(process.env.SLACK_WEBHOOK_URL!, {\n      method: 'POST',\n      headers: { 'Content-Type': 'application\u002Fjson' },\n      body: JSON.stringify({\n        text: `New user signed up: ${name} (${email})`,\n      }),\n    })\n  }\n\n  \u002F\u002F Always return 200 to acknowledge receipt\n  return new Response('OK', { status: 200 })\n}\n```\n\n**Also include proxy.ts (Next.js \u003C=15: middleware.ts) to make the route public:**\n```typescript\n\u002F\u002F proxy.ts (Next.js \u003C=15: middleware.ts)\nimport { clerkMiddleware, createRouteMatcher } from '@clerk\u002Fnextjs\u002Fserver'\nconst isPublicRoute = createRouteMatcher(['\u002Fapi\u002Fwebhooks(.*)'])\nexport default clerkMiddleware(async (auth, req) => {\n  if (!isPublicRoute(req)) await auth.protect()\n})\n```\n\n## Full Example: Organization Membership Sync to Database\n\n```typescript\n\u002F\u002F app\u002Fapi\u002Fwebhooks\u002Froute.ts\nimport { verifyWebhook } from '@clerk\u002Fnextjs\u002Fwebhooks'\nimport { NextRequest } from 'next\u002Fserver'\nimport { db } from '@\u002Flib\u002Fdb' \u002F\u002F your database client\n\nexport async function POST(req: NextRequest) {\n  \u002F\u002F ALWAYS verify signature - never skip, even for simple handlers\n  let evt\n  try {\n    evt = await verifyWebhook(req) \u002F\u002F uses CLERK_WEBHOOK_SIGNING_SECRET env var\n  } catch (err) {\n    console.error('Webhook verification failed:', err)\n    return new Response('Verification failed', { status: 400 })\n  }\n\n  if (evt.type === 'organization.created') {\n    const { id, name } = evt.data\n    await db.workspaces.create({\n      data: { orgId: id, name, createdAt: new Date() },\n    })\n  }\n\n  if (evt.type === 'organizationMembership.created') {\n    \u002F\u002F Extract organization ID, user ID, and role from payload\n    const { organization, public_user_data, role } = evt.data\n    const orgId = organization.id\n    const userId = public_user_data.user_id\n\n    \u002F\u002F Add to team_members table\n    await db.team_members.create({\n      data: { orgId, userId, role },\n    })\n\n    \u002F\u002F Create workspace record for new member\n    await db.workspaces.create({\n      data: { orgId, userId, createdAt: new Date() },\n    })\n  }\n\n  if (evt.type === 'organizationMembership.deleted') {\n    \u002F\u002F Extract organization ID and user ID from payload\n    const { organization, public_user_data } = evt.data\n    const orgId = organization.id\n    const userId = public_user_data.user_id\n\n    \u002F\u002F Remove from team_members table\n    await db.team_members.delete({\n      where: { orgId, userId },\n    })\n\n    \u002F\u002F Remove workspace record\n    await db.workspaces.deleteMany({\n      where: { orgId, userId },\n    })\n  }\n\n  \u002F\u002F Return 200 status on success\n  return new Response('OK', { status: 200 })\n}\n```\n\n## Other Frameworks\n\nFor Express, Astro, Fastify, Nuxt, React Router, and TanStack Start, use the framework-specific `verifyWebhook` adapter. Each Clerk SDK package ships its own (`@clerk\u002Fexpress\u002Fwebhooks`, `@clerk\u002Fastro\u002Fwebhooks`, `@clerk\u002Ffastify\u002Fwebhooks`, etc.).\n\nSee `references\u002Fframeworks.md` for full handler examples per framework.\n\n## Type Narrowing for `evt.data`\n\n`verifyWebhook` returns `WebhookEvent`, a discriminated union of all event types. Narrow with `evt.type` to get type-safe access to `evt.data`:\n\n```typescript\nconst evt = await verifyWebhook(req)\n\nif (evt.type === 'user.created') {\n  \u002F\u002F evt.data is now UserJSON, autocompletes id, email_addresses, etc.\n  console.log(evt.data.id)\n}\n```\n\nFor manual typing of nested payloads, import the JSON types from your framework's webhook subpath: `DeletedObjectJSON`, `EmailJSON`, `OrganizationInvitationJSON`, `OrganizationJSON`, `OrganizationMembershipJSON`, `SessionJSON`, `SMSMessageJSON`, `UserJSON`.\n\n## Payload Field Reference\n\n### User events (`user.created`, `user.updated`, `user.deleted`)\n```typescript\nconst {\n  id,                  \u002F\u002F Clerk user ID\n  email_addresses,     \u002F\u002F array; [0].email_address is primary email\n  first_name,\n  last_name,\n  image_url,\n  public_metadata,\n} = evt.data\n```\n\n### Organization events (`organization.created`, `organization.updated`, `organization.deleted`)\n```typescript\nconst {\n  id,    \u002F\u002F org ID\n  name,  \u002F\u002F org name\n  slug,\n} = evt.data\n```\n\n### Organization Membership events (`organizationMembership.created`, `organizationMembership.updated`, `organizationMembership.deleted`)\n```typescript\nconst {\n  organization,        \u002F\u002F { id, name, ... }\n  public_user_data,    \u002F\u002F { user_id, first_name, last_name, ... }\n  role,                \u002F\u002F e.g. 'org:admin', 'org:member'\n} = evt.data\n\u002F\u002F Access: organization.id, public_user_data.user_id, role\n```\n\n## Supported Events (Full Catalog)\n\n**User**: `user.created` `user.updated` `user.deleted`\n\n**Session**: `session.created` `session.ended` `session.removed` `session.revoked`\n\n**Organization**: `organization.created` `organization.updated` `organization.deleted`\n\n**Organization Membership**: `organizationMembership.created` `organizationMembership.updated` `organizationMembership.deleted`\n\n**Organization Domain**: `organizationDomain.created` `organizationDomain.updated` `organizationDomain.deleted`\n\n**Organization Invitation**: `organizationInvitation.accepted` `organizationInvitation.created` `organizationInvitation.revoked`\n\n**Communication**: `email.created` `sms.created`\n\n**Waitlist**: `waitlistEntry.created` `waitlistEntry.updated`\n\n**Permission**: `permission.created` `permission.updated` `permission.deleted`\n\n**Role**: `role.created` `role.updated` `role.deleted`\n\n**Subscription**: `subscription.created` `subscription.updated` `subscription.active` `subscription.pastDue`\n\n**Subscription Item**: `subscriptionItem.created` `subscriptionItem.active` `subscriptionItem.updated` `subscriptionItem.canceled` `subscriptionItem.upcoming` `subscriptionItem.ended` `subscriptionItem.abandoned` `subscriptionItem.incomplete` `subscriptionItem.pastDue` `subscriptionItem.freeTrialEnding`\n\n**Payment**: `paymentAttempt.created` `paymentAttempt.updated`\n\n## Webhook Reliability\n\n**Retries**: Svix retries failed webhooks on a set schedule (see [Svix Retry Schedule](https:\u002F\u002Fdocs.svix.com\u002Fretries)). Return 2xx to succeed, 4xx\u002F5xx to retry. Use the `svix-id` header as an idempotency key to deduplicate retried events.\n\n**Replay**: Failed webhooks can be replayed from Dashboard.\n\n## Common Pitfalls\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| Verification fails (Next.js) | Wrong import or usage | Use `@clerk\u002Fnextjs\u002Fwebhooks`, pass `req` directly |\n| Verification fails (Express) | Using `express.json()` | Use `express.raw({ type: 'application\u002Fjson' })` for webhook route |\n| Route not found (404) | Wrong path | Use `\u002Fapi\u002Fwebhooks` or preserve existing path |\n| Not authorized (401) | Route is protected by middleware | Make route public in `clerkMiddleware()` |\n| No data in DB | Async job pending | Wait\u002Fcheck logs |\n| Duplicate entries | Only handling `user.created` | Also handle `user.updated` |\n| Timeouts | Handler too slow | Queue async work, return 200 first |\n\n## Testing & Deployment\n\n**Local**: Use the Clerk CLI's first-party tunnel — no auth or linked project needed:\n\n```sh\nclerk webhooks listen --token \"$(clerk webhooks token)\" --forward-to http:\u002F\u002Flocalhost:3000\u002Fapi\u002Fwebhooks\n```\n\nAdd the printed relay URL (`https:\u002F\u002Fwebhooks.clerk.com\u002Fin\u002Fc_...\u002F`) as a webhook endpoint in the Dashboard — events don't flow until you do. `svix-*` headers are preserved, so `verifyWebhook()` works against that endpoint's signing secret as usual. Flags, offline signature checks (`clerk webhooks verify`), and agent-mode behavior are in the `clerk-cli` skill. Without the CLI, tunnel `localhost:3000` yourself (`ngrok`, `localtunnel`, `Cloudflare Tunnel`) and add the public URL to the Dashboard endpoint.\n\n**Production**: Update webhook endpoint URL to production domain. Copy `CLERK_WEBHOOK_SIGNING_SECRET` to production env vars.\n\n## References\n\n| Reference | Description |\n|-----------|-------------|\n| `references\u002Fframeworks.md` | Webhook handler examples for Express, Astro, Fastify, Nuxt, React Router, TanStack Start |\n\n## See Also\n\n- `clerk-cli` - `clerk webhooks listen`\u002F`verify` for local webhook testing\n- `clerk-setup` - Initial Clerk install\n- `clerk-orgs` - Org membership events\n- `clerk-billing` - Subscription, subscription item, and payment attempt events\n- `clerk-backend-api` - Sync via direct API calls","# Webhooks\n\nOutput complete, working webhook handlers with `verifyWebhook(req)` verification in every handler.\n\n## When to Use Webhooks\n\nWebhooks 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:\n\n- Database sync (a separate users \u002F orgs table that follows Clerk)\n- Notifications (welcome emails, Slack pings, internal alerts)\n- Integrations triggered by lifecycle events\n\nDo 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](https:\u002F\u002Fclerk.com\u002Fdocs\u002Fguides\u002Fsessions\u002Fsession-tokens) 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.\n\n## Verify Every Webhook\n\nUse `verifyWebhook(req)` from the framework-specific package (`@clerk\u002Fnextjs\u002Fwebhooks`, `@clerk\u002Fexpress\u002Fwebhooks`, 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.\n\n## Make the Webhook Route Public\n\nWebhook routes must be excluded from Clerk middleware protection. Without this, Clerk returns 401.\n\n```typescript\n\u002F\u002F proxy.ts (Next.js \u003C=15: middleware.ts)\nimport { clerkMiddleware, createRouteMatcher } from '@clerk\u002Fnextjs\u002Fserver'\n\nconst isPublicRoute = createRouteMatcher(['\u002Fapi\u002Fwebhooks(.*)'])\n\nexport default clerkMiddleware(async (auth, req) => {\n  if (!isPublicRoute(req)) await auth.protect()\n})\n```\n\n## Complete Webhook Handler (Next.js App Router)\n\n```typescript\n\u002F\u002F app\u002Fapi\u002Fwebhooks\u002Froute.ts\nimport { verifyWebhook } from '@clerk\u002Fnextjs\u002Fwebhooks'\nimport { NextRequest } from 'next\u002Fserver'\nimport { db } from '@\u002Flib\u002Fdb'\n\nexport async function POST(req: NextRequest) {\n  \u002F\u002F ALWAYS verify - never skip, even for notification-only handlers\n  let evt\n  try {\n    evt = await verifyWebhook(req) \u002F\u002F uses CLERK_WEBHOOK_SIGNING_SECRET automatically\n  } catch (err) {\n    console.error('Webhook verification failed:', err)\n    return new Response('Verification failed', { status: 400 })\n  }\n\n  if (evt.type === 'user.created') {\n    const { id, email_addresses, first_name, last_name } = evt.data\n    const email = email_addresses[0]?.email_address\n    const name = `${first_name ?? ''} ${last_name ?? ''}`.trim()\n    await db.users.create({ data: { clerkId: id, email, name } })\n  }\n\n  if (evt.type === 'user.updated') {\n    const { id, email_addresses, first_name, last_name } = evt.data\n    const email = email_addresses[0]?.email_address\n    await db.users.update({ where: { clerkId: id }, data: { email, first_name, last_name } })\n  }\n\n  if (evt.type === 'user.deleted') {\n    const { id } = evt.data\n    await db.users.delete({ where: { clerkId: id } })\n  }\n\n  if (evt.type === 'organizationMembership.created') {\n    const { organization, public_user_data, role } = evt.data\n    const orgId = organization.id\n    const userId = public_user_data.user_id\n    await db.teamMembers.create({ data: { orgId, userId, role } })\n  }\n\n  if (evt.type === 'organizationMembership.deleted') {\n    const { organization, public_user_data } = evt.data\n    const orgId = organization.id\n    const userId = public_user_data.user_id\n    await db.teamMembers.delete({ where: { orgId_userId: { orgId, userId } } })\n  }\n\n  return new Response('OK', { status: 200 })\n}\n```\n\n## Full Example: Welcome Email (Resend) + Slack Notification on user.created\n\nNotification-only handlers still verify the signature. Same pattern as the database-sync handler:\n\n```typescript\n\u002F\u002F app\u002Fapi\u002Fwebhooks\u002Froute.ts\nimport { verifyWebhook } from '@clerk\u002Fnextjs\u002Fwebhooks'\nimport { NextRequest } from 'next\u002Fserver'\nimport { Resend } from 'resend'\n\nconst resend = new Resend(process.env.RESEND_API_KEY)\n\nexport async function POST(req: NextRequest) {\n  \u002F\u002F Step 1: ALWAYS verify the webhook signature - NEVER skip this\n  let evt\n  try {\n    evt = await verifyWebhook(req) \u002F\u002F uses CLERK_WEBHOOK_SIGNING_SECRET env var\n  } catch (err) {\n    console.error('Webhook verification failed:', err)\n    return new Response('Verification failed', { status: 400 })\n  }\n\n  \u002F\u002F Step 2: Listen for user.created event\n  if (evt.type === 'user.created') {\n    \u002F\u002F Step 3: Extract user email and name from webhook payload\n    const { id, email_addresses, first_name, last_name } = evt.data\n    const email = email_addresses[0]?.email_address\n    const name = `${first_name ?? ''} ${last_name ?? ''}`.trim()\n\n    \u002F\u002F Step 4: Call Resend API to send welcome email\n    await resend.emails.send({\n      from: 'noreply@yourdomain.com',\n      to: email,\n      subject: 'Welcome!',\n      html: `\u003Cp>Hi ${name}, welcome to our app!\u003C\u002Fp>`,\n    })\n\n    \u002F\u002F Step 5: Post notification to Slack channel\n    await fetch(process.env.SLACK_WEBHOOK_URL!, {\n      method: 'POST',\n      headers: { 'Content-Type': 'application\u002Fjson' },\n      body: JSON.stringify({\n        text: `New user signed up: ${name} (${email})`,\n      }),\n    })\n  }\n\n  \u002F\u002F Always return 200 to acknowledge receipt\n  return new Response('OK', { status: 200 })\n}\n```\n\n**Also include proxy.ts (Next.js \u003C=15: middleware.ts) to make the route public:**\n```typescript\n\u002F\u002F proxy.ts (Next.js \u003C=15: middleware.ts)\nimport { clerkMiddleware, createRouteMatcher } from '@clerk\u002Fnextjs\u002Fserver'\nconst isPublicRoute = createRouteMatcher(['\u002Fapi\u002Fwebhooks(.*)'])\nexport default clerkMiddleware(async (auth, req) => {\n  if (!isPublicRoute(req)) await auth.protect()\n})\n```\n\n## Full Example: Organization Membership Sync to Database\n\n```typescript\n\u002F\u002F app\u002Fapi\u002Fwebhooks\u002Froute.ts\nimport { verifyWebhook } from '@clerk\u002Fnextjs\u002Fwebhooks'\nimport { NextRequest } from 'next\u002Fserver'\nimport { db } from '@\u002Flib\u002Fdb' \u002F\u002F your database client\n\nexport async function POST(req: NextRequest) {\n  \u002F\u002F ALWAYS verify signature - never skip, even for simple handlers\n  let evt\n  try {\n    evt = await verifyWebhook(req) \u002F\u002F uses CLERK_WEBHOOK_SIGNING_SECRET env var\n  } catch (err) {\n    console.error('Webhook verification failed:', err)\n    return new Response('Verification failed', { status: 400 })\n  }\n\n  if (evt.type === 'organization.created') {\n    const { id, name } = evt.data\n    await db.workspaces.create({\n      data: { orgId: id, name, createdAt: new Date() },\n    })\n  }\n\n  if (evt.type === 'organizationMembership.created') {\n    \u002F\u002F Extract organization ID, user ID, and role from payload\n    const { organization, public_user_data, role } = evt.data\n    const orgId = organization.id\n    const userId = public_user_data.user_id\n\n    \u002F\u002F Add to team_members table\n    await db.team_members.create({\n      data: { orgId, userId, role },\n    })\n\n    \u002F\u002F Create workspace record for new member\n    await db.workspaces.create({\n      data: { orgId, userId, createdAt: new Date() },\n    })\n  }\n\n  if (evt.type === 'organizationMembership.deleted') {\n    \u002F\u002F Extract organization ID and user ID from payload\n    const { organization, public_user_data } = evt.data\n    const orgId = organization.id\n    const userId = public_user_data.user_id\n\n    \u002F\u002F Remove from team_members table\n    await db.team_members.delete({\n      where: { orgId, userId },\n    })\n\n    \u002F\u002F Remove workspace record\n    await db.workspaces.deleteMany({\n      where: { orgId, userId },\n    })\n  }\n\n  \u002F\u002F Return 200 status on success\n  return new Response('OK', { status: 200 })\n}\n```\n\n## Other Frameworks\n\nFor Express, Astro, Fastify, Nuxt, React Router, and TanStack Start, use the framework-specific `verifyWebhook` adapter. Each Clerk SDK package ships its own (`@clerk\u002Fexpress\u002Fwebhooks`, `@clerk\u002Fastro\u002Fwebhooks`, `@clerk\u002Ffastify\u002Fwebhooks`, etc.).\n\nSee `references\u002Fframeworks.md` for full handler examples per framework.\n\n## Type Narrowing for `evt.data`\n\n`verifyWebhook` returns `WebhookEvent`, a discriminated union of all event types. Narrow with `evt.type` to get type-safe access to `evt.data`:\n\n```typescript\nconst evt = await verifyWebhook(req)\n\nif (evt.type === 'user.created') {\n  \u002F\u002F evt.data is now UserJSON, autocompletes id, email_addresses, etc.\n  console.log(evt.data.id)\n}\n```\n\nFor manual typing of nested payloads, import the JSON types from your framework's webhook subpath: `DeletedObjectJSON`, `EmailJSON`, `OrganizationInvitationJSON`, `OrganizationJSON`, `OrganizationMembershipJSON`, `SessionJSON`, `SMSMessageJSON`, `UserJSON`.\n\n## Payload Field Reference\n\n### User events (`user.created`, `user.updated`, `user.deleted`)\n```typescript\nconst {\n  id,                  \u002F\u002F Clerk user ID\n  email_addresses,     \u002F\u002F array; [0].email_address is primary email\n  first_name,\n  last_name,\n  image_url,\n  public_metadata,\n} = evt.data\n```\n\n### Organization events (`organization.created`, `organization.updated`, `organization.deleted`)\n```typescript\nconst {\n  id,    \u002F\u002F org ID\n  name,  \u002F\u002F org name\n  slug,\n} = evt.data\n```\n\n### Organization Membership events (`organizationMembership.created`, `organizationMembership.updated`, `organizationMembership.deleted`)\n```typescript\nconst {\n  organization,        \u002F\u002F { id, name, ... }\n  public_user_data,    \u002F\u002F { user_id, first_name, last_name, ... }\n  role,                \u002F\u002F e.g. 'org:admin', 'org:member'\n} = evt.data\n\u002F\u002F Access: organization.id, public_user_data.user_id, role\n```\n\n## Supported Events (Full Catalog)\n\n**User**: `user.created` `user.updated` `user.deleted`\n\n**Session**: `session.created` `session.ended` `session.removed` `session.revoked`\n\n**Organization**: `organization.created` `organization.updated` `organization.deleted`\n\n**Organization Membership**: `organizationMembership.created` `organizationMembership.updated` `organizationMembership.deleted`\n\n**Organization Domain**: `organizationDomain.created` `organizationDomain.updated` `organizationDomain.deleted`\n\n**Organization Invitation**: `organizationInvitation.accepted` `organizationInvitation.created` `organizationInvitation.revoked`\n\n**Communication**: `email.created` `sms.created`\n\n**Waitlist**: `waitlistEntry.created` `waitlistEntry.updated`\n\n**Permission**: `permission.created` `permission.updated` `permission.deleted`\n\n**Role**: `role.created` `role.updated` `role.deleted`\n\n**Subscription**: `subscription.created` `subscription.updated` `subscription.active` `subscription.pastDue`\n\n**Subscription Item**: `subscriptionItem.created` `subscriptionItem.active` `subscriptionItem.updated` `subscriptionItem.canceled` `subscriptionItem.upcoming` `subscriptionItem.ended` `subscriptionItem.abandoned` `subscriptionItem.incomplete` `subscriptionItem.pastDue` `subscriptionItem.freeTrialEnding`\n\n**Payment**: `paymentAttempt.created` `paymentAttempt.updated`\n\n## Webhook Reliability\n\n**Retries**: Svix retries failed webhooks on a set schedule (see [Svix Retry Schedule](https:\u002F\u002Fdocs.svix.com\u002Fretries)). Return 2xx to succeed, 4xx\u002F5xx to retry. Use the `svix-id` header as an idempotency key to deduplicate retried events.\n\n**Replay**: Failed webhooks can be replayed from Dashboard.\n\n## Common Pitfalls\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| Verification fails (Next.js) | Wrong import or usage | Use `@clerk\u002Fnextjs\u002Fwebhooks`, pass `req` directly |\n| Verification fails (Express) | Using `express.json()` | Use `express.raw({ type: 'application\u002Fjson' })` for webhook route |\n| Route not found (404) | Wrong path | Use `\u002Fapi\u002Fwebhooks` or preserve existing path |\n| Not authorized (401) | Route is protected by middleware | Make route public in `clerkMiddleware()` |\n| No data in DB | Async job pending | Wait\u002Fcheck logs |\n| Duplicate entries | Only handling `user.created` | Also handle `user.updated` |\n| Timeouts | Handler too slow | Queue async work, return 200 first |\n\n## Testing & Deployment\n\n**Local**: Use the Clerk CLI's first-party tunnel — no auth or linked project needed:\n\n```sh\nclerk webhooks listen --token \"$(clerk webhooks token)\" --forward-to http:\u002F\u002Flocalhost:3000\u002Fapi\u002Fwebhooks\n```\n\nAdd the printed relay URL (`https:\u002F\u002Fwebhooks.clerk.com\u002Fin\u002Fc_...\u002F`) as a webhook endpoint in the Dashboard — events don't flow until you do. `svix-*` headers are preserved, so `verifyWebhook()` works against that endpoint's signing secret as usual. Flags, offline signature checks (`clerk webhooks verify`), and agent-mode behavior are in the `clerk-cli` skill. Without the CLI, tunnel `localhost:3000` yourself (`ngrok`, `localtunnel`, `Cloudflare Tunnel`) and add the public URL to the Dashboard endpoint.\n\n**Production**: Update webhook endpoint URL to production domain. Copy `CLERK_WEBHOOK_SIGNING_SECRET` to production env vars.\n\n## References\n\n| Reference | Description |\n|-----------|-------------|\n| `references\u002Fframeworks.md` | Webhook handler examples for Express, Astro, Fastify, Nuxt, React Router, TanStack Start |\n\n## See Also\n\n- `clerk-cli` - `clerk webhooks listen`\u002F`verify` for local webhook testing\n- `clerk-setup` - Initial Clerk install\n- `clerk-orgs` - Org membership events\n- `clerk-billing` - Subscription, subscription item, and payment attempt events\n- `clerk-backend-api` - Sync via direct API calls",{"license":15,"metadata":24,"description":7},{"author":25,"version":26},"clerk","1.2.0","main","7540bbccf0c1ded6156a467b02c95b61ad62413f",".agents\u002Fskills\u002Fclerk-webhooks","https:\u002F\u002Fgithub.com\u002FNeelakshSaxena\u002FVayu","https:\u002F\u002Fgithub.com\u002FNeelakshSaxena","Currently exploring the intersection of tech","2026-09-11 03:02:31",{"source":8,"skillName":5,"commands":35,"prompt":45,"zipAvailable":46},[36,39,42],{"tool":37,"command":38},"npx","npx skills add NeelakshSaxena\u002FVayu --skill clerk-webhooks",{"tool":40,"command":41},"bunx","bunx skills add NeelakshSaxena\u002FVayu --skill clerk-webhooks",{"tool":43,"command":44},"pnpm","pnpm dlx skills add NeelakshSaxena\u002FVayu --skill clerk-webhooks","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FNeelakshSaxena\u002FVayu\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fclerk-webhooks\u002FSKILL.md",true,[48,54],{"path":49,"resourceType":50,"resourceTypeDesc":51,"sizeBytes":52,"sourceHtmlUrl":53},"evals\u002Fevals.json","REFERENCE","参考文档",3750,"https:\u002F\u002Fgithub.com\u002FNeelakshSaxena\u002FVayu\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fclerk-webhooks\u002Fevals\u002Fevals.json",{"path":55,"resourceType":50,"resourceTypeDesc":51,"sizeBytes":56,"sourceHtmlUrl":57},"references\u002Fframeworks.md",6073,"https:\u002F\u002Fgithub.com\u002FNeelakshSaxena\u002FVayu\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fclerk-webhooks\u002Freferences\u002Fframeworks.md",[59,67,74,81,88,95],{"skillNo":60,"name":61,"nameZh":6,"description":62,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":63,"licenseFileUrl":6,"sourceHtmlUrl":64,"categories":65,"keywords":66,"publishedAt":19},"01M7ACCCVNCFKMA9X6D15X6G98","runpodctl","Runpod CLI for managing GPU\u002FCPU workloads from the terminal — pods, serverless endpoints, templates, network volumes, Hub deploys, models, SSH, and file transfer (send\u002Freceive). Use for terminal\u002FCI\u002Fscripting, Hub browse\u002Fdeploy, SSH setup, `doctor`, or when the Runpod MCP tools are not connected. For structured tool calls in an MCP-enabled session, prefer runpod-mcp.","Apache-2.0","https:\u002F\u002Fgithub.com\u002FNeelakshSaxena\u002FVayu\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Frunpodctl\u002FSKILL.md",[],[],{"skillNo":68,"name":69,"nameZh":6,"description":70,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":63,"licenseFileUrl":6,"sourceHtmlUrl":71,"categories":72,"keywords":73,"publishedAt":19},"01M7ACC63SRHEA5KMCHSMZK2TC","runpod","Start here for any Runpod task — running GPU\u002FCPU pods, deploying serverless endpoints, templates, network volumes, building images, or understanding how Runpod works. Routes to the right skill (runpod-mcp, runpodctl, flash, companion-clis, runpod-usage, runpod-templates, runpod-migrate) and indexes two dozen live-verified end-to-end examples (golden paths) — use it when the lane is unclear, and for any multi-step or provisioning task even when it is not.","https:\u002F\u002Fgithub.com\u002FNeelakshSaxena\u002FVayu\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Frunpod\u002FSKILL.md",[],[],{"skillNo":75,"name":76,"nameZh":6,"description":77,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":63,"licenseFileUrl":6,"sourceHtmlUrl":78,"categories":79,"keywords":80,"publishedAt":19},"01M7ACC0Q1C89N9BZBV91CTQTF","runpod-usage","How Runpod works and how to work it — pods vs serverless, GPU\u002FVRAM selection, storage, building a container, networking, plus the agentic pod development loop (provision → ssh-exec → set up → poll readiness) and on-pod install hygiene (uv\u002Fapt). Use to answer \"how does X work\", \"which GPU\", \"how do I build a container\", or \"how do I stand up a workload on a pod\". Guidance, not a tool — execute with runpodctl, runpod-mcp, or flash.","https:\u002F\u002Fgithub.com\u002FNeelakshSaxena\u002FVayu\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Frunpod-usage\u002FSKILL.md",[],[],{"skillNo":82,"name":83,"nameZh":6,"description":84,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":63,"licenseFileUrl":6,"sourceHtmlUrl":85,"categories":86,"keywords":87,"publishedAt":19},"01M7ACBRPE345GF5GM5B8P8RRC","runpod-templates","Runpod's official prebuilt pod templates (ComfyUI, PyTorch, and others): what each image ships, which ports and paths it uses, how to pick one, how to pin a version, and what is missing on first boot. Use when a task says \"run \u003CX> on a pod\" and an official template already covers it, instead of building an image — and when a user needs help with or wants to fix something about a Runpod template they are already running (won't boot, can't reach the UI, missing models, wrong CUDA line, broken ComfyUI workflow metadata on imported workflows): start here and route onward. Deploy with runpodctl or runpod-mcp; end-to-end walkthroughs live in the runpod router's golden paths.","https:\u002F\u002Fgithub.com\u002FNeelakshSaxena\u002FVayu\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Frunpod-templates\u002FSKILL.md",[],[],{"skillNo":89,"name":90,"nameZh":6,"description":91,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":63,"licenseFileUrl":6,"sourceHtmlUrl":92,"categories":93,"keywords":94,"publishedAt":19},"01M7ACBJATHKVX1TWES2F44GY8","runpod-migrate","Migrate a codebase from the Runpod GraphQL API or REST v1 to REST v2 — inventory which parts use which API version, rewrite the call sites, flag breaking changes, and verify. Use when someone asks to move to v2, asks what v2 would change, or asks which Runpod API their code is on. For managing infrastructure rather than migrating code, use runpod-mcp or runpodctl.","https:\u002F\u002Fgithub.com\u002FNeelakshSaxena\u002FVayu\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Frunpod-migrate\u002FSKILL.md",[],[],{"skillNo":96,"name":97,"nameZh":6,"description":98,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":63,"licenseFileUrl":6,"sourceHtmlUrl":99,"categories":100,"keywords":101,"publishedAt":19},"01M7ACBC7GHVH6T9YEAPCG2AP8","runpod-mcp","Manage Runpod infrastructure — pods, serverless endpoints, jobs, templates, network volumes, container-registry auth, GPU\u002FCPU catalog, and billing — via the Runpod MCP server's structured tool calls. Use when the Runpod MCP tools (create-pod, list-endpoints, …) are connected in this session, or to connect them (hosted OAuth or local npx). Prefer this over runpodctl for plain infra CRUD when MCP is available; use runpodctl for the terminal, file transfer, or SSH setup.","https:\u002F\u002Fgithub.com\u002FNeelakshSaxena\u002FVayu\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Frunpod-mcp\u002FSKILL.md",[],[]]