Clerk Webhook

curl --request POST \
  --url https://api.example.com/clerk

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/clerk",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/clerk"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/clerk")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

POST

clerk

Clerk Webhook

curl --request POST \
  --url https://api.example.com/clerk

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/clerk",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/clerk"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/clerk")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

Overview

This webhook endpoint receives user lifecycle events from Clerk authentication service. It automatically syncs user data between Clerk and the SkillRise database.

Authentication

Webhook Signature Verification

Clerk uses Svix for webhook delivery. All requests are verified using HMAC signatures. Required Headers:

svix-id: Unique message identifier
svix-timestamp: Unix timestamp when the webhook was sent
svix-signature: HMAC signature for verification

Verification Process: The endpoint verifies the webhook signature using the CLERK_WEBHOOK_SECRET environment variable:

const webhook = new Webhook(process.env.CLERK_WEBHOOK_SECRET)
await webhook.verify(JSON.stringify(req.body), {
  'svix-id': req.headers['svix-id'],
  'svix-timestamp': req.headers['svix-timestamp'],
  'svix-signature': req.headers['svix-signature'],
})

Failed signature verification results in an error being thrown and the webhook being rejected.

Event Types

user.created

Fired when a new user signs up through Clerk. Action: Creates a new user record in the SkillRise database. Payload Example:

{
  "type": "user.created",
  "data": {
    "id": "user_2abc123xyz",
    "email_addresses": [
      {
        "email_address": "user@example.com"
      }
    ],
    "first_name": "John",
    "last_name": "Doe",
    "image_url": "https://img.clerk.com/user_2abc123xyz"
  }
}

Database Fields:

_id: Clerk user ID
email: Primary email address
name: Concatenation of first_name and last_name
imageUrl: Profile image URL

user.updated

Fired when a user updates their profile in Clerk. Action: Updates the existing user record in the database. Payload Example:

{
  "type": "user.updated",
  "data": {
    "id": "user_2abc123xyz",
    "email_addresses": [
      {
        "email_address": "newemail@example.com"
      }
    ],
    "first_name": "Jane",
    "last_name": "Smith",
    "image_url": "https://img.clerk.com/user_2abc123xyz"
  }
}

Updated Fields:

email
name
imageUrl

user.deleted

Fired when a user account is deleted in Clerk. Action: Deletes the corresponding user record from the database. Payload Example:

{
  "type": "user.deleted",
  "data": {
    "id": "user_2abc123xyz"
  }
}

Request Format

Headers

Header	Type	Required	Description
`svix-id`	string	Yes	Unique message identifier
`svix-timestamp`	string	Yes	Unix timestamp of webhook delivery
`svix-signature`	string	Yes	HMAC signature for verification
`Content-Type`	string	Yes	Must be `application/json`

Body

{
  "type": "user.created | user.updated | user.deleted",
  "data": {
    "id": "string",
    "email_addresses": [
      {
        "email_address": "string"
      }
    ],
    "first_name": "string",
    "last_name": "string",
    "image_url": "string"
  }
}

Response Format

Success Response

Status Code: 200 OK

{}

All successful webhook processing returns an empty JSON object.

Error Response

Status Code: 500 Internal Server Error

{
  "success": false,
  "message": "An unexpected error occurred"
}

Error Handling

The endpoint implements comprehensive error handling:

Signature Verification Failure: If the Svix signature verification fails, an error is thrown and caught by the error handler
Database Errors: Any database operation failures are caught and return a 500 error
Unknown Event Types: Events with unrecognized types are silently acknowledged with an empty response

Unknown event types return a successful empty response to prevent Clerk from retrying the webhook.

Security Best Practices

Environment Variables: Store CLERK_WEBHOOK_SECRET securely in environment variables
Signature Verification: Always verify the Svix signature before processing any webhook data
HTTPS Only: Configure Clerk to only send webhooks to HTTPS endpoints in production
Idempotency: The endpoint handles duplicate webhooks gracefully (e.g., update operations are idempotent)

Configuration

Clerk Dashboard Setup

Navigate to Webhooks in your Clerk dashboard
Click Add Endpoint
Enter your endpoint URL: https://yourdomain.com/clerk
Select events to subscribe to:
- user.created
- user.updated
- user.deleted
Copy the Signing Secret and set it as CLERK_WEBHOOK_SECRET

Environment Variables

CLERK_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxxxxxxx

Implementation Reference

Location: server/controllers/webhooks.js:8

export const clerkWebhooks = async (req, res) => {
  try {
    const webhook = new Webhook(process.env.CLERK_WEBHOOK_SECRET)
    
    await webhook.verify(JSON.stringify(req.body), {
      'svix-id': req.headers['svix-id'],
      'svix-timestamp': req.headers['svix-timestamp'],
      'svix-signature': req.headers['svix-signature'],
    })
    
    const { data, type } = req.body
    
    switch (type) {
      case 'user.created':
        // Create user in database
        break
      case 'user.updated':
        // Update user in database
        break
      case 'user.deleted':
        // Delete user from database
        break
      default:
        // Acknowledge unknown events
    }
    
    res.json({})
  } catch (error) {
    res.status(500).json({ 
      success: false, 
      message: 'An unexpected error occurred' 
    })
  }
}

Overview

Course API

User API

AI Features API

Quiz API

Community API

Educator API

Admin API

Webhooks

Clerk Webhook

Overview

Authentication

Webhook Signature Verification

Event Types

user.created

user.updated

user.deleted

Request Format

Headers

Body

Response Format

Success Response

Error Response

Error Handling

Security Best Practices

Configuration

Clerk Dashboard Setup

Environment Variables

Implementation Reference

​Overview

​Authentication

​Webhook Signature Verification

​Event Types

​user.created

​user.updated

​user.deleted

​Request Format

​Headers

​Body

​Response Format

​Success Response

​Error Response

​Error Handling

​Security Best Practices

​Configuration

​Clerk Dashboard Setup

​Environment Variables

​Implementation Reference

Overview

Authentication

Webhook Signature Verification

Event Types

user.created

user.updated

user.deleted

Request Format

Headers

Body

Response Format

Success Response

Error Response

Error Handling

Security Best Practices

Configuration

Clerk Dashboard Setup

Environment Variables

Implementation Reference