Webhooks

Clerk webhooks allow you to receive event notifications from Clerk. Clerk will send a POST request to a URL you specify when certain events happen in your Clerk account.

Clerk uses Svix to send our webhooks and you can find more information about Svix here.

You can find the Webhook signing secret when you click on the endpoint you created under Webhooks on the Clerk dashboard.

Supported webhook events

Emails

email.created

Organization

organization.created
organization.deleted
organization.updated

Organization Invitation

organizationInvitation.accepted
organizationInvitation.created
organizationInvitation.revoked

Organization Membership

organizationMembership.created
organizationMembership.deleted
organizationMembership.updated

Session

session.created
session.ended
session.removed
session.revoked

SMS

sms.created

User

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 the User object . For organization.* event type, the payload will always be an organization (except for when it is deleted).

Below is an example of a webhook payload for a user.created event:

{
  "data": {
    "birthday": "",
    "created_at": 1654012591514,
    "email_addresses": [
      {
        "email_address": "example@example.org",
        "id": "idn_29w83yL7CwVlJXylYLxcslromF1",
        "linked_to": [],
        "object": "email_address",
        "verification": {
          "status": "verified",
          "strategy": "ticket"
        }
      }
    ],
    "external_accounts": [],
    "external_id": "567772",
    "first_name": "Example",
    "gender": "",
    "id": "user_29w83sxmDNGwOuEthce5gg56FcC",
    "last_name": "Example",
    "last_sign_in_at": 1654012591514,
    "object": "user",
    "password_enabled": true,
    "phone_numbers": [],
    "primary_email_address_id": "idn_29w83yL7CwVlJXylYLxcslromF1",
    "primary_phone_number_id": null,
    "primary_web3_wallet_id": null,
    "private_metadata": {},
    "profile_image_url": "https://www.gravatar.com/avatar?d=mp",
    "public_metadata": {},
    "two_factor_enabled": false,
    "unsafe_metadata": {},
    "updated_at": 1654012591835,
    "username": null,
    "web3_wallets": []
  },
  "object": "event",
  "type": "user.created"
}

Typescript Support

Clerk provides the types as part of our SDK offering. Below is an example of type usage in a webhook handler:

import type { WebhookEvent } from "@clerk/clerk-sdk-node"
 
const handler = req => {
  const evt = req.body.evt as WebhookEvent;
  switch (evt.type) {
    case 'user.created':
      // UserJSON.first_name is a string
      const firstName = evt.data.first_name
      // UserJSON.last_name is a string
      const lastName = evt.data.last_name
      // UserJSON.email_addresses is an array of EmailAddressJSON
      const emails = evt.data.email_addresses;
  }
}

How to use webhooks

You can find a guide on how to use webhooks to sync your data to your database here.