A 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:
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
&emdash; The 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.
- Create a route handler at your preferred location.
- Create an instance of
createWebhooksHandler
, passing in a configuration object with a series of callback functions. - Export the handler's
POST
method asPOST
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.
import { createWebhooksHandler } from "@brianmmdev/clerk-webhooks-handler";
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:
export type WebhookRegistrationConfig = {
secret?: string
onUserCreated?: HandlerFn<UserJSON>;
onUserUpdated?: HandlerFn<UserJSON>;
onUserDeleted?: HandlerFn<DeletedObjectJSON>;
onEmailCreated?: HandlerFn<EmailJSON>;
onSmsCreated?: HandlerFn<SMSMessageJSON>;
onSessionCreated?: HandlerFn<SessionJSON>;
onSessionEnded?: HandlerFn<SessionJSON>;
onSessionRemoved?: HandlerFn<SessionJSON>;
onSessionRevoked?: HandlerFn<SessionJSON>;
onOrganizationCreated?: HandlerFn<OrganizationJSON>;
onOrganizationUpdated?: HandlerFn<OrganizationJSON>;
onOrganizationDeleted?: HandlerFn<DeletedObjectJSON>;
onOrganizationMembershipCreated?: HandlerFn<OrganizationMembershipJSON>;
onOrganizationMembershipDeleted?: HandlerFn<OrganizationMembershipJSON>;
onOrganizationMembershipUpdated?: HandlerFn<OrganizationMembershipJSON>;
onOrganizationInvitationAccepted?: HandlerFn<OrganizationInvitationJSON>;
onOrganizationInvitationCreated?: HandlerFn<OrganizationInvitationJSON>;
onOrganizationInvitationRevoked?: HandlerFn<OrganizationInvitationJSON>;
}
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.