Handle webhook events in your application

Receive real-time notifications about authentication events in your application using Scalekit webhooks

Webhooks provide real-time notifications about authentication and user management events in your Scalekit environment. Instead of polling for changes, your application receives instant notifications when users sign up, log in, join organizations, or when other important events occur.

Webhook delivery: Scalekit queues an event, posts the payload to your endpoint, and your app verifies the signature before processing

Webhooks enable your app to react immediately to changes in your auth stack through:

Real-time updates: Get notified immediately when events occur
Reduced API calls: No need to poll for changes
Event-driven architecture: Build responsive workflows that react to user actions
Reliable delivery: Scalekit ensures webhook delivery with automatic retries

Webhook event object

All webhook payloads follow a standardized structure with metadata and event-specific data in the data field.

{
  "spec_version": "1", // The version of the event specification format. Currently "1".
  "id": "evt_123456789", // A unique identifier for the event (e.g., evt_123456789).
  "object": "DirectoryUser", // The type of object, such as "DirectoryUser", "Directory" or "Connection". Domain events omit it.
  "environment_id": "env_123456789", // The ID of the environment where the event occurred.
  "occurred_at": "2024-08-21T10:20:17.072Z", // ISO 8601 timestamp indicating when the event occurred.
  "organization_id": "org_123456789", // The organization the event is about. Not sent on user.* events; read data.organization.id or data.user_session.organization_id instead.
  "type": "organization.directory.user_created", // The specific event type (e.g., "organization.directory.user_created").
  "data": { // Event-specific payload. Its fields depend on the event type.
    "id": "diruser_123456789",
    "organization_id": "org_123456789",
    "email": "user@example.com",
    "name": "John Doe"
    // ...more user fields
  }
}

Configure webhooks in the dashboard

Set up webhook endpoints and select which events you want to receive through the Scalekit dashboard.

In your Scalekit dashboard, navigate to Developers > Webhooks
Click Add Endpoint and provide:
- Endpoint URL - Your application’s webhook handler URL (e.g., https://yourapp.com/webhooks/scalekit)
- Description - Optional description for this endpoint
Choose which events you want to receive. For example:
- User events: user.signup, user.login, user.logout, user.organization_invitation, and user.organization_membership_created, _updated and _deleted
- Organization events: organization.created, organization.updated, organization.deleted
- SSO events: organization.sso_created, organization.sso_enabled, organization.sso_disabled, organization.sso_deleted
- Directory events: organization.directory_created, organization.directory_enabled and siblings, plus organization.directory.user_* and organization.directory.group_*
See the webhooks reference for every event and its payload.
Copy the Signing Secret - you’ll use this to verify webhook authenticity in your application
Use the Send Test Event button to verify your endpoint is working correctly

Implement webhook handlers

Create secure webhook handlers in your application to process incoming events from Scalekit.

Set up webhook endpoint

Create an HTTP POST endpoint in your application to receive webhook payloads from Scalekit.


3 collapsed lines
1
import express from 'express'
2
import { Scalekit } from '@scalekit-sdk/node'
3

4
const app = express()
5
const scalekit = new Scalekit(
6
  process.env.SCALEKIT_ENVIRONMENT_URL,
7
  process.env.SCALEKIT_CLIENT_ID,
8
  process.env.SCALEKIT_CLIENT_SECRET
9
)
10

11
// HMAC is over the raw bytes. Parsing JSON first changes whitespace and fails verify.
12
app.use('/webhooks/scalekit', express.raw({ type: 'application/json' }))
13

14
app.post('/webhooks/scalekit', async (req, res) => {
15
  const secret = process.env.SCALEKIT_WEBHOOK_SECRET
16
  const payload = req.body.toString()
17
  const headers = {
18
    'webhook-id': req.headers['webhook-id'],
19
    'webhook-timestamp': req.headers['webhook-timestamp'],
20
    'webhook-signature': req.headers['webhook-signature'],
21
  }
22

23
  try {
24
    scalekit.verifyWebhookPayload(secret, headers, payload)
25
  } catch (error) {
26
    console.error('Invalid webhook signature')
27
    return res.status(401).json({ error: 'Invalid signature' })
28
  }
29

30
  const event = JSON.parse(payload)
31
  await processWebhookEvent(event)
32
  res.status(201).json({ received: true })
33
})


5 collapsed lines
1
import json
2
import os
3

4
from flask import Flask, jsonify, request
5
from scalekit import ScalekitClient
6

7
app = Flask(__name__)
8
scalekit_client = ScalekitClient(
9
    env_url=os.environ["SCALEKIT_ENVIRONMENT_URL"],
10
    client_id=os.environ["SCALEKIT_CLIENT_ID"],
11
    client_secret=os.environ["SCALEKIT_CLIENT_SECRET"],
12
)
13

14
@app.route("/webhooks/scalekit", methods=["POST"])
15
def handle_webhook():
16
    secret = os.environ.get("SCALEKIT_WEBHOOK_SECRET")
17
    raw_body = request.get_data()
18
    headers = {
19
        "webhook-id": request.headers.get("webhook-id"),
20
        "webhook-timestamp": request.headers.get("webhook-timestamp"),
21
        "webhook-signature": request.headers.get("webhook-signature"),
22
    }
23

24
    try:
25
        scalekit_client.verify_webhook_payload(secret, headers, raw_body)
26
    except Exception:
27
        print("Invalid webhook signature")
28
        return jsonify({"error": "Invalid signature"}), 401
29

30
    event = json.loads(raw_body.decode("utf-8"))
31
    process_webhook_event(event)
32
    return jsonify({"received": True}), 201


11 collapsed lines
1
package main
2

3
import (
4
    "encoding/json"
5
    "io"
6
    "net/http"
7
    "os"
8

9
    "github.com/gin-gonic/gin"
10
    scalekit "github.com/scalekit-inc/scalekit-sdk-go"
11
)
12

13
var scalekitClient = scalekit.NewScalekitClient(
14
    os.Getenv("SCALEKIT_ENVIRONMENT_URL"),
15
    os.Getenv("SCALEKIT_CLIENT_ID"),
16
    os.Getenv("SCALEKIT_CLIENT_SECRET"),
17
)
18

19
func handleWebhook(c *gin.Context) {
20
    rawBody, err := io.ReadAll(c.Request.Body)
21
    if err != nil {
22
        c.JSON(http.StatusBadRequest, gin.H{"error": "Failed to read body"})
23
        return
24
    }
25

26
    headers := map[string]string{
27
        "webhook-id":        c.GetHeader("webhook-id"),
28
        "webhook-timestamp": c.GetHeader("webhook-timestamp"),
29
        "webhook-signature": c.GetHeader("webhook-signature"),
30
    }
31

32
    valid, err := scalekitClient.VerifyWebhookPayload(
33
        os.Getenv("SCALEKIT_WEBHOOK_SECRET"),
34
        headers,
35
        rawBody,
36
    )
37
    if err != nil || !valid {
38
        c.JSON(http.StatusUnauthorized, gin.H{"error": "Invalid signature"})
39
        return
40
    }
41

42
    var event map[string]interface{}
43
    if err := json.Unmarshal(rawBody, &event); err != nil {
44
        c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid JSON"})
45
        return
46
    }
47

48
    processWebhookEvent(event)
49
    c.JSON(http.StatusCreated, gin.H{"received": true})
50
}


8 collapsed lines
1
import com.fasterxml.jackson.databind.ObjectMapper;
2
import com.scalekit.ScalekitClient;
3
import java.nio.charset.StandardCharsets;
4
import java.util.HashMap;
5
import java.util.Map;
6
import org.springframework.http.HttpStatus;
7
import org.springframework.http.ResponseEntity;
8
import org.springframework.web.bind.annotation.PostMapping;
9
import org.springframework.web.bind.annotation.RequestBody;
10
import org.springframework.web.bind.annotation.RequestHeader;
11
import org.springframework.web.bind.annotation.RestController;
12

13
@RestController
14
public class WebhookController {
15

16
  private final ScalekitClient scalekitClient;
17
  private final ObjectMapper objectMapper = new ObjectMapper();
18

19
  @PostMapping("/webhooks/scalekit")
20
  public ResponseEntity<Map<String, Object>> handleWebhook(
21
    @RequestBody String rawBody,
22
    @RequestHeader Map<String, String> requestHeaders
23
  ) {
24
    Map<String, String> headers = new HashMap<>();
25
    headers.put("webhook-id", requestHeaders.get("webhook-id"));
26
    headers.put("webhook-timestamp", requestHeaders.get("webhook-timestamp"));
27
    headers.put("webhook-signature", requestHeaders.get("webhook-signature"));
28

29
    try {
30
      scalekitClient
31
        .webhook()
32
        .verifyWebhookPayload(
33
          System.getenv("SCALEKIT_WEBHOOK_SECRET"),
34
          headers,
35
          rawBody.getBytes(StandardCharsets.UTF_8)
36
        );
37
    } catch (Exception error) {
38
      return ResponseEntity.status(HttpStatus.UNAUTHORIZED).body(
39
        Map.of("error", "Invalid signature")
40
      );
41
    }
42

43
    try {
44
      Map<String, Object> event = objectMapper.readValue(rawBody, Map.class);
45
      processWebhookEvent(event);
46
      return ResponseEntity.status(HttpStatus.CREATED).body(Map.of("received", true));
47
    } catch (Exception error) {
48
      return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(
49
        Map.of("error", "Webhook processing failed")
50
      );
51
    }
52
  }
53
}

Process webhook events

Handle different event types based on your application’s needs.

1
async function processWebhookEvent(event) {
2
  console.log(`Processing event: ${event.type}`);
3

4
  switch (event.type) {
5
    case 'user.organization_membership_created':
6
      // A user joined an organization. data has the user and the organization.
7
      await handleMemberAdded(event.data.user, event.data.organization);
8
      break;
9

10
    case 'user.organization_membership_deleted':
11
      // A user left an organization
12
      await revokeAccess(event.data.user.id, event.data.organization.id);
13
      break;
14

15
    case 'organization.created':
16
      // data is the organization
17
      await handleOrganizationCreated(event.data);
18
      break;
19

20
    default:
21
      console.log(`Unhandled event type: ${event.type}`);
22
  }
23
}
24

25
async function handleMemberAdded(user, organization) {
26
  // Use case: Sync the user to your database, send a welcome email, set up defaults
27
  console.log(`New member: ${user.email} in org: ${organization.display_name}`);
28

29
  // Sync to your database
30
  await syncUserToDatabase(user, organization);
31

32
  // Send a welcome email. Profile fields are in user.user_profile.
33
  await sendWelcomeEmail(user.email, user.user_profile.given_name);
34

35
  // Set up the user's workspace or default settings
36
  await setupUserDefaults(user.id, organization.id);
37
}

1
def process_webhook_event(event):
2
    print(f'Processing event: {event["type"]}')
3

4
    event_type = event['type']
5
    event_data = event['data']
6

7
    if event_type == 'user.organization_membership_created':
8
        # A user joined an organization. data has the user and the organization.
9
        handle_member_added(event_data['user'], event_data['organization'])
10
    elif event_type == 'user.organization_membership_deleted':
11
        # A user left an organization
12
        revoke_access(event_data['user']['id'], event_data['organization']['id'])
13
    elif event_type == 'organization.created':
14
        # data is the organization
15
        handle_organization_created(event_data)
16
    else:
17
        print(f'Unhandled event type: {event_type}')
18

19
def handle_member_added(user, organization):
20
    # Use case: Sync the user to your database, send a welcome email, set up defaults
21
    print(f'New member: {user["email"]} in org: {organization["display_name"]}')
22

23
    # Sync to your database
24
    sync_user_to_database(user, organization)
25

26
    # Send a welcome email. Profile fields are in user['user_profile'].
27
    send_welcome_email(user['email'], user['user_profile']['given_name'])
28

29
    # Set up the user's workspace or default settings
30
    setup_user_defaults(user['id'], organization['id'])

1
func processWebhookEvent(event map[string]interface{}) {
2
    eventType := event["type"].(string)
3
    eventData := event["data"].(map[string]interface{})
4

5
    fmt.Printf("Processing event: %s\n", eventType)
6

7
    switch eventType {
8
    case "user.organization_membership_created":
9
        // A user joined an organization. data has the user and the organization.
10
        user := eventData["user"].(map[string]interface{})
11
        organization := eventData["organization"].(map[string]interface{})
12
        handleMemberAdded(user, organization)
13

14
    case "user.organization_membership_deleted":
15
        // A user left an organization
16
        user := eventData["user"].(map[string]interface{})
17
        organization := eventData["organization"].(map[string]interface{})
18
        revokeAccess(user["id"].(string), organization["id"].(string))
19

20
    case "organization.created":
21
        // data is the organization
22
        handleOrganizationCreated(eventData)
23

24
    default:
25
        fmt.Printf("Unhandled event type: %s\n", eventType)
26
    }
27
}
28

29
func handleMemberAdded(user, organization map[string]interface{}) {
30
    // Use case: Sync the user to your database, send a welcome email, set up defaults
31
    fmt.Printf("New member: %s in org: %s\n",
32
        user["email"], organization["display_name"])
33

34
    // Sync to your database
35
    syncUserToDatabase(user, organization)
36

37
    // Send a welcome email. Profile fields are in user["user_profile"].
38
    profile := user["user_profile"].(map[string]interface{})
39
    sendWelcomeEmail(user["email"].(string), profile["given_name"].(string))
40

41
    // Set up the user's workspace or default settings
42
    setupUserDefaults(user["id"].(string), organization["id"].(string))
43
}

1
private void processWebhookEvent(Map<String, Object> event) {
2
    String eventType = (String) event.get("type");
3
    Map<String, Object> eventData = (Map<String, Object>) event.get("data");
4

5
    System.out.println("Processing event: " + eventType);
6

7
    switch (eventType) {
8
        case "user.organization_membership_created": {
9
            // A user joined an organization. data has the user and the organization.
10
            Map<String, Object> user = (Map<String, Object>) eventData.get("user");
11
            Map<String, Object> organization = (Map<String, Object>) eventData.get("organization");
12
            handleMemberAdded(user, organization);
13
            break;
14
        }
15

16
        case "user.organization_membership_deleted": {
17
            // A user left an organization
18
            Map<String, Object> user = (Map<String, Object>) eventData.get("user");
19
            Map<String, Object> organization = (Map<String, Object>) eventData.get("organization");
20
            revokeAccess((String) user.get("id"), (String) organization.get("id"));
21
            break;
22
        }
23

24
        case "organization.created":
25
            // data is the organization
26
            handleOrganizationCreated(eventData);
27
            break;
28

29
        default:
30
            System.out.println("Unhandled event type: " + eventType);
31
    }
32
}
33

34
private void handleMemberAdded(Map<String, Object> user, Map<String, Object> organization) {
35
    // Use case: Sync the user to your database, send a welcome email, set up defaults
36
    System.out.println("New member: " + user.get("email") +
37
        " in org: " + organization.get("display_name"));
38

39
    // Sync to your database
40
    syncUserToDatabase(user, organization);
41

42
    // Send a welcome email. Profile fields are in user_profile.
43
    Map<String, Object> profile = (Map<String, Object>) user.get("user_profile");
44
    sendWelcomeEmail((String) user.get("email"), (String) profile.get("given_name"));
45

46
    // Set up the user's workspace or default settings
47
    setupUserDefaults((String) user.get("id"), (String) organization.get("id"));
48
}

Verify with the three webhook headers

Call the SDK verify method before you parse JSON. Pass the dashboard signing secret (whsec_…), the raw body, and these headers:

Header	Role
`webhook-id`	Message ID in the HMAC. Same value on every retry
`webhook-timestamp`	Unix seconds. The SDK rejects timestamps more than 5 minutes in the past or future
`webhook-signature`	Space-separated `v1,<base64>` values

Language	Method
Node.js	`scalekit.verifyWebhookPayload(secret, headers, payload)`
Python	`scalekit_client.verify_webhook_payload(secret, headers, payload)`
Go	`scalekitClient.VerifyWebhookPayload(secret, headers, payload)`
Java	`scalekitClient.webhook().verifyWebhookPayload(secret, headers, payload)`

Node, Python, and Java throw when the signature is invalid. Go returns (false, error).

There is no webhooks.verifySignature method and no scalekit-signature header.

Respond to webhook event

Scalekit expects specific HTTP status codes in response to webhook deliveries. Return appropriate status codes to control retry behavior.

Return success responses
Section titled “Return success responses”

Return success status codes when webhooks are processed successfully.

Status Code Description
200 OK Webhook processed successfully
201 Created Recommended Webhook processed and resource created
202 Accepted Webhook accepted for asynchronous processing

Status Code	Description
`200 OK`	Webhook processed successfully
`201 Created` Recommended	Webhook processed and resource created
`202 Accepted`	Webhook accepted for asynchronous processing

Handle error responses

Return error status codes to indicate processing failures.

Status Code	Description
`400 Bad Request`	Invalid payload or malformed request
`401 Unauthorized`	Invalid webhook signature
`403 Forbidden`	Webhook not authorized
`422 Unprocessable Entity`	Valid request but cannot process
`500 Internal Server Error`	Server error during processing

Scalekit retries every failed delivery with exponential backoff. Any status code outside 2xx triggers a retry, including 4xx codes. Each attempt waits up to 30 seconds for a response.

Attempt	Delay after the previous attempt
1	Immediately
2	5 seconds
3	5 minutes
4	30 minutes
5	2 hours
6	5 hours
7	10 hours
8	10 hours

After the eighth attempt fails, the delivery is marked as failed. That happens about 27 hours and 35 minutes after the first attempt. If an endpoint fails every delivery for 5 days, Scalekit disables it.

Webhook failures are logged in your Scalekit dashboard for monitoring and debugging.

Testing webhooks

Test your webhook implementation locally before deploying to production.

Use ngrok to expose your local development server for webhook testing.

# Install ngrok
npm install -g ngrok

# Start your local server
npm run dev

# In another terminal, expose your local server
ngrok http 3000

# Use the ngrok URL in your Scalekit dashboard
# Example: https://abc123.ngrok.io/webhooks/scalekit

Common webhook use cases

Webhooks enable common integration patterns:

User lifecycle management: Sync user data across systems, provision accounts in downstream services, and trigger onboarding workflows when users sign up or update their profiles
Organization and membership management: Set up workspaces when organizations are created, update user access when they join or leave organizations, and provision organization-specific resources
Authentication monitoring: Track login patterns, update last-seen timestamps, and trigger security alerts for suspicious activity

Webhook event reference

You now have a complete webhook implementation that can reliably process authentication events from Scalekit. Consider these additional improvements:

Organization events

User events

Directory events

SSO connection events

Role events

Permission events