A package to streamline the configuration of Clerk webhooks in a Next.js application.
npm install @brianmmdev/clerk-webhooks-handlerA package to streamline the configuration of Clerk webhooks.
> ⚠ This project is not officially supported by Clerk. Use at your own discretion.
The goal of this package is to make it easier to work with Clerk webhooks by abstracting away the process of parsing the incoming event type and payload, as well as automatically validating the signature of the incoming request.
The result is a single method that uses callback functions and passes through fully-typed versions of the supported payloads, making it simpler to perform operations such as updating database records, sending custom notifications, and any other custom logic that you'd like to build.
This package is deployed to NPM and can be installed with the following command:
``bash`
npm install @brianmmdev/clerk-webhooks-handler
To run this project, you will need to add the following environment variables to your .env file:
- WEBHOOK_SECRET — The _Signing Secret_ value obtained from the Clerk dashboard when registering a new endpoint.
While this package can theoretically be used with any JavaScript web framework, it has only been tested with Next.js as of now, so this example will be using Next.js.
1. Create a route handler at your preferred location.
2. Create an instance of createWebhooksHandler, passing in a configuration object with a series of callback functions.POST
3. Export the handler's method as POST so Next.js will pass web requests into it.
The following example shows what this route handler would look like with the onUserUpdated which fires when a user is updated in Clerk, and onSessionCreated when a session is created.
`ts
import { createWebhooksHandler } from "@brianmmdev/clerk-webhooks-handler";
import { UserJSON, SessionJSON } from "@clerk/nextjs/server";
const handler = createWebhooksHandler({
// Add/remove optional handlers to get access to the data.
onUserUpdated: async (payload: UserJSON) => {
// Handle the payload...
},
onSessionCreated: async (payload: SessionJSON) => {
// Handle the payload...
}
})
export const POST = handler.POST
`
The WebhookRegistrationConfig object defines all supported callbacks, which in turn correspond to their webhook event in Clerk:
`ts`
export type WebhookRegistrationConfig = {
secret?: string
onEmailCreated?: HandlerFn
onOrganizationCreated?: HandlerFn
onOrganizationDeleted?: HandlerFn
onOrganizationUpdated?: HandlerFn
onOrganizationInvitationAccepted?: HandlerFn
onOrganizationInvitationCreated?: HandlerFn
onOrganizationInvitationRevoked?: HandlerFn
onOrganizationMembershipCreated?: HandlerFn
onOrganizationMembershipDeleted?: HandlerFn
onOrganizationMembershipUpdated?: HandlerFn
onPermissionCreated?: HandlerFn
onPermissionDeleted?: HandlerFn
onPermissionUpdated?: HandlerFn
onRoleCreated?: HandlerFn
onRoleDeleted?: HandlerFn
onRoleUpdated?: HandlerFn
onSessionCreated?: HandlerFn
onSessionEnded?: HandlerFn
onSessionPending?: HandlerFn
onSessionRemoved?: HandlerFn
onSessionRevoked?: HandlerFn
onSmsCreated?: HandlerFn
onUserCreated?: HandlerFn
onUserCreatedAtEdge?: HandlerFn
onUserDeleted?: HandlerFn
onUserUpdated?: HandlerFn
onWaitlistEntryCreated?: HandlerFn
onWaitlistEntryUpdated?: HandlerFn
}
In the event that a callback is not defined for the corresponding webhook, the package will respond with a 404` status to the caller.
Contributions are always welcome! To contribute to this project, fork it into your own GitHub account or organization, make the necessary changes, and create a pull request into this repository.
If I do not respond in a timely manner, feel free to ping or DM me on Twitter: @brianmmdev
If you have any feedback, please reach out to me on Twitter: @brianmmdev
To report issues or suggest improvements, feel free to [create an issue]().