Docs

Webhooks overview

A webhook is an event-driven method of communication between applications.

Unlike typical APIs where you would need to poll for data very frequently to get it "real-time", webhooks only send data when there is an event to trigger the webhook. This makes webhooks seem "real-time", but it's important to note that they are asynchronous.

For example, if you are onboarding a new user, you can't rely on the webhook delivery as part of that flow. Typically the delivery will happen quickly, but it's not guaranteed to be delivered immediately or at all. Webhooks are best used for things like sending a notification or updating a database, but not for synchronous flows where you need to know the webhook was delivered before moving on to the next step. If you need a synchronous flow, please see our Onboarding Guide as one example of implementing that.

Clerk webhooks

Clerk webhooks allow you to receive event notifications from Clerk, such as when a user is created or updated. When an event occurs, Clerk will send a POST request to your webhook endpoint configured for the event type. You can then use the information from the webhook's request payload to trigger actions in your app, such as sending a notification or updating a database.

Clerk uses Svix to send our webhooks.

You can find the Webhook signing secret when you click on the endpoint you created on the Webhooks page in the Clerk Dashboard.

Supported webhook events

To find a list of all the events Clerk supports:

  1. Navigate to the Clerk Dashboard.
  2. In the navigation sidenav, select Webhooks.
  3. Select the Event Catalog tab.

Payload structure

The payload of a webhook is a JSON object that contains the following properties:

  • data: 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.
  • object: always set to event.
  • type: the type of event that triggered the webhook.

The following example shows the payload of 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",
    "image_url": "https://img.clerk.com/xxxxxx",
    "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"
}

The payload should always be treated as unsafe until you validate the incoming webhook. Webhooks will originate from another server and be sent to your application as a POST request. A bad actor would fake a webhook event to try and gain access to your application or data.

How Clerk handles delivery issues

Retry

Svix will use a set schedule and retry any webhooks that fail. To see the up-to-date schedule, check out the Svix Retry Schedule.

If Svix is attempting and failing to send a webhook, and that endpoint is removed or disabled from the Webhooks page of the Clerk Dashboard, then the attempts will also be disabled.

Replay

If a webhook message or multiple webhook messages fail to send, you have an option to replay the webhook messages. This protects against your service having downtime or against a misconfigured endpoint.

To replay webhook messages:

  1. Navigate to the Clerk Dashboard.
  2. In the navigation sidenav, select Webhooks.
  3. Select the affected endpoint.
  4. In the Message Attempts section, next to the message you want to replay, select the menu icon on the right side, and then select Replay.
  5. The Replay Messages menu will appear. You can choose to:
  • Resend the specific message you selected.
  • Resend all failed messages since the first failed message in that date range.
  • Resend all missing messages since the first failed message in that date range.

Sync data to your database

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

Protect your webhooks from abuse

To ensure that the API route receiving the webhook can only be hit by your app, there are a few protections you can put in place:

Feedback

What did you think of this content?
Edit this page on GitHub