Webhooks

Receive event notifications with Clerk webhooks

If you need to keep your local store in sync with up to date user info, or you want to send a welcome email, you'll need to setup a webhook, so Clerk can tell you about events that happen on your instance.

For more information on how to setup webhooks in your instance and how to architecture your application in order to be updated with Clerk events the right way, check our Sync data to your back-end guide.

Supported events

Here is a list of all the events you can choose from:

email.created
organization.created
organization.deleted
organization.updated
organizationInvitation.accepted
organizationInvitation.created
organizationInvitation.revoked
organizationMembership.created
organizationMembership.deleted
organizationMembership.updated
session.created
session.ended
session.removed
session.revoked
sms.created
user.created
user.deleted
user.updated

Payload structure

The payload of the message includes the type of the event in the type property.

The data property contains the actual payload sent by Clerk. The payload can be a different object depending on the event type. For example, for user.* events, the payload will always be a user object. For organization.* event type, the payload will always be an organization (except for when it is deleted).

{
   "object": "event",
   "type": "user.created",
   "data": {
      // user object
  }
}

Verifying requests

Behind the scenes, we're using Svix to power our webhooks, when ingesting events, they've written extensive directions on how you should verify webhooks. Look at Svix's documentation on how to verify that webhook requests are valid.

If you don't verify the request, your app will be susceptible to a number of attacks since your webhook endpoint is open to the public.

Typescript support

You can import the WebhookEvent type and use it like so:

1
import type { WebhookEvent } from "@clerk/clerk-sdk-node" 
2

3
const handler = req => {
4
  const evt = req.body.evt as WebhookEvent; 
5
  switch (evt.type) {
6
    case 'user.created': // this is typed
7
      evt.data.firstName // this is also typed
8
  }
9
}