Implement webhooks

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

Receive real-time notifications when authentication and user management events occur in your application. For example, when users are provisioned, updated, or deprovisioned through directory sync, Scalekit sends webhook events to your application so you can keep your systems synchronized automatically.

Scalekit sends POST requests to your webhook endpoint with event details, and waits for a 201 response to confirm receipt. For example, one event fires immediately after a user is provisioned via SCIM. We’ll explore more events throughout this guide.

Implementing webhooks

You can receive webhooks for directory sync events, user provisioning changes, and other authentication events.

Event	When it fires
`organization.directory_enabled`	Directory synchronization is activated for an organization
`organization.directory_disabled`	Directory synchronization is deactivated for an organization
`organization.directory.user_created`	New user is provisioned via SCIM
`organization.directory.user_updated`	User profile is updated via SCIM
`organization.directory.user_deleted`	User is deprovisioned via SCIM
`organization.directory.group_created`	New group is created via SCIM
`organization.directory.group_updated`	Group is updated via SCIM
`organization.directory.group_deleted`	Group is deleted via SCIM

At each event occurrence, Scalekit sends a POST request to your webhook endpoint with the relevant event details.

Verify the webhook request

Create an HTTPS endpoint that receives and verifies POST requests from Scalekit. This critical security step ensures requests are authentic and haven’t been tampered with.

1
// Security: ALWAYS verify requests are from Scalekit before processing
2
// This prevents unauthorized parties from triggering your webhook handlers
3

4
app.post('/webhooks/manage-users', async (req, res) => {
5
  try {
6
    // Parse the webhook headers for signature verification
7
    const headers = {
8
      'webhook-id': req.headers['webhook-id'],
9
      'webhook-signature': req.headers['webhook-signature'],
10
      'webhook-timestamp': req.headers['webhook-timestamp']
11
    };
12
    const event = req.body;
13

14
    // Get the signing secret from Scalekit dashboard > Settings > Webhooks
15
    // Store this securely in environment variables
16
    const webhookSecret = process.env.SCALEKIT_WEBHOOK_SECRET;
17

18
    // Initialize Scalekit client (reference installation guide for setup)
19
    const scalekit = new ScalekitClient(
20
      process.env.SCALEKIT_ENVIRONMENT_URL,
21
      process.env.SCALEKIT_CLIENT_ID,
22
      process.env.SCALEKIT_CLIENT_SECRET
23
    );
24

25
    // Verify the webhook payload signature
26
    // This confirms the request is from Scalekit and hasn't been tampered with
27
    await scalekit.verifyWebhookPayload(webhookSecret, headers, event);
28

29
    // ✓ Request verified - proceed to business logic (next step)
30

31
  } catch (error) {
32
    console.error('Webhook verification failed:', error);
33
    // Return 401 on verification failures to fail securely
34
    return res.status(401).json({
35
      error: 'Invalid signature'
36
    });
37
  }
38
});

1
# Security: ALWAYS verify requests are from Scalekit before processing
2
# This prevents unauthorized parties from triggering your webhook handlers
3

4
from flask import Flask, request, jsonify
5
import os
6

7
app = Flask(__name__)
8

9
@app.route('/webhooks/manage-users', methods=['POST'])
10
def handle_webhook():
11
    try:
12
        # Parse the webhook headers for signature verification
13
        headers = {
14
            'webhook-id': request.headers.get('webhook-id'),
15
            'webhook-signature': request.headers.get('webhook-signature'),
16
            'webhook-timestamp': request.headers.get('webhook-timestamp')
17
        }
18
        body = request.get_data()
19

20
        # Get the signing secret from Scalekit dashboard > Settings > Webhooks
21
        # Store this securely in environment variables
22
        webhook_secret = os.getenv('SCALEKIT_WEBHOOK_SECRET')
23

24
        # Initialize Scalekit client (reference installation guide for setup)
25
        scalekit_client = ScalekitClient(
26
            env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
27
            client_id=os.getenv("SCALEKIT_CLIENT_ID"),
28
            client_secret=os.getenv("SCALEKIT_CLIENT_SECRET")
29
        )
30

31
        # Verify the webhook payload signature
32
        # This confirms the request is from Scalekit and hasn't been tampered with
33
        is_valid = scalekit_client.verify_webhook_payload(
34
            secret=webhook_secret,
35
            headers=headers,
36
            payload=body
37
        )
38

39
        if not is_valid:
40
            return jsonify({
41
                'error': 'Invalid signature'
42
            }), 401
43

44
        # ✓ Request verified - proceed to business logic (next step)
45

46
    except Exception as error:
47
        print(f'Webhook verification failed: {error}')
48
        # Return 401 on verification failures to fail securely
49
        return jsonify({
50
            'error': 'Invalid signature'
51
        }), 401

1
// Security: ALWAYS verify requests are from Scalekit before processing
2
// This prevents unauthorized parties from triggering your webhook handlers
3

4
package main
5

6
import (
7
    "io"
8
    "log"
9
    "net/http"
10
    "os"
11

12
    "github.com/gin-gonic/gin"
13
)
14

15
type WebhookResponse struct {
16
    Received bool              `json:"received,omitempty"`
17
    Error    *WebhookError     `json:"error,omitempty"`
18
}
19

20
type WebhookError struct {
21
    Message string `json:"message"`
22
}
23

24
func handleWebhook(c *gin.Context) {
25
    // Parse the webhook headers for signature verification
26
    headers := map[string]string{
27
        "webhook-id":        c.GetHeader("webhook-id"),
28
        "webhook-signature": c.GetHeader("webhook-signature"),
29
        "webhook-timestamp": c.GetHeader("webhook-timestamp"),
30
    }
31

32
    // Read raw body for verification
33
    bodyBytes, err := io.ReadAll(c.Request.Body)
34
    if err != nil {
35
        c.JSON(http.StatusBadRequest, WebhookResponse{
36
            Error: &WebhookError{Message: "Unable to read request"},
37
        })
38
        return
39
    }
40

41
    // Get the signing secret from Scalekit dashboard > Settings > Webhooks
42
    // Store this securely in environment variables
43
    webhookSecret := os.Getenv("SCALEKIT_WEBHOOK_SECRET")
44

45
    // Initialize Scalekit client (reference installation guide for setup)
46
    scalekitClient := scalekit.NewScalekitClient(
47
        os.Getenv("SCALEKIT_ENVIRONMENT_URL"),
48
        os.Getenv("SCALEKIT_CLIENT_ID"),
49
        os.Getenv("SCALEKIT_CLIENT_SECRET"),
50
    )
51

52
    // Verify the webhook payload signature
53
    // This confirms the request is from Scalekit and hasn't been tampered with
54
    _, err = scalekitClient.VerifyWebhookPayload(
55
        webhookSecret,
56
        headers,
57
        bodyBytes,
58
    )
59
    if err != nil {
60
        log.Printf("Webhook verification failed: %v", err)
61
        // Return 401 on verification failures to fail securely
62
        c.JSON(http.StatusUnauthorized, WebhookResponse{
63
            Error: &WebhookError{Message: "Invalid signature"},
64
        })
65
        return
66
    }
67

68
    // ✓ Request verified - proceed to business logic (next step)
69
}

1
// Security: ALWAYS verify requests are from Scalekit before processing
2
// This prevents unauthorized parties from triggering your webhook handlers
3

4
package com.example.webhooks;
5

6
import org.springframework.http.ResponseEntity;
7
import org.springframework.web.bind.annotation.*;
8

9
import java.util.Map;
10

11
@RestController
12
@RequestMapping("/webhooks")
13
public class WebhookController {
14

15
    @PostMapping("/manage-users")
16
    public ResponseEntity<Map<String, Object>> handleWebhook(
17
        @RequestBody String body,
18
        @RequestHeader Map<String, String> headers
19
    ) {
20
        try {
21
            // Get the signing secret from Scalekit dashboard > Settings > Webhooks
22
            // Store this securely in environment variables
23
            String webhookSecret = System.getenv("SCALEKIT_WEBHOOK_SECRET");
24

25
            // Initialize Scalekit client (reference installation guide for setup)
26
            ScalekitClient scalekitClient = new ScalekitClient(
27
                System.getenv("SCALEKIT_ENVIRONMENT_URL"),
28
                System.getenv("SCALEKIT_CLIENT_ID"),
29
                System.getenv("SCALEKIT_CLIENT_SECRET")
30
            );
31

32
            // Verify the webhook payload signature
33
            // This confirms the request is from Scalekit and hasn't been tampered with
34
            boolean valid = scalekitClient.webhook()
35
                .verifyWebhookPayload(webhookSecret, headers, body.getBytes());
36

37
            if (!valid) {
38
                // Return 401 on invalid signatures
39
                return ResponseEntity.status(401).body(Map.of(
40
                    "error", "Invalid signature"
41
                ));
42
            }
43

44
            // ✓ Request verified - proceed to business logic (next step)
45

46
        } catch (Exception error) {
47
            System.err.println("Webhook verification failed: " + error.getMessage());
48
            // Return 401 on verification failures to fail securely
49
            return ResponseEntity.status(401).body(Map.of(
50
                "error", "Invalid signature"
51
            ));
52
        }
53
    }
54
}

Process the event and respond

After verification, parse the webhook event, apply your custom business logic, and return a 201 response to acknowledge receipt.

1
// Use case: Sync user data from directory to your application
2
// Examples: User provisioning, deprovisioning, group membership updates
3

4
app.post('/webhooks/manage-users', async (req, res) => {
5
  try {
6
    // ... (verification code from Step 1)
7

8
    // Parse the verified webhook event
9
    const event = req.body;
10

11
    // Process webhook asynchronously (don't block the response)
12
    // This allows us to respond quickly to prevent unnecessary retries
13
    processWebhookEvent(event).catch(error => {
14
      // Log error but don't throw - we already acknowledged receipt
15
      console.error('Async processing error:', error);
16
    });
17

18
    // IMPORTANT: Always respond with 201 to acknowledge receipt
19
    // Scalekit expects this response within 10 seconds
20
    return res.status(201).json({ received: true });
21

22
  } catch (error) {
23
    console.error('Webhook error:', error);
24
    return res.status(401).json({ error: 'Invalid signature' });
25
  }
26
});
27

28
async function processWebhookEvent(event) {
29
  console.log(`Processing event: ${event.type}`);
30

31
  switch (event.type) {
32
    case 'organization.directory.user_created':
33
      // Sync new user to your database
34
      await handleUserCreated(event.data);
35
      break;
36

37
    case 'organization.directory.user_updated':
38
      // Update user profile in your database
39
      await handleUserUpdated(event.data);
40
      break;
41

42
    case 'organization.directory.user_deleted':
43
      // Deprovision user from your application
44
      await handleUserDeleted(event.data);
45
      break;
46

47
    case 'organization.directory.group_created':
48
      // Handle new group creation
49
      await handleGroupCreated(event.data);
50
      break;
51

52
    default:
53
      console.log(`Unhandled event type: ${event.type}`);
54
  }
55
}
56

57
async function handleUserCreated(data) {
58
  // Use case: Sync new user to your database when provisioned via SCIM
59
  console.log(`New user created: ${data.email} in org: ${data.organization_id}`);
60

61
  // Sync to your database
62
  await syncUserToDatabase(data);
63

64
  // Grant default permissions
65
  await setupUserDefaults(data.id, data.organization_id);
66
}

1
# Use case: Sync user data from directory to your application
2
# Examples: User provisioning, deprovisioning, group membership updates
3

4
import json
5

6
@app.route('/webhooks/manage-users', methods=['POST'])
7
def handle_webhook():
8
    try:
9
        # ... (verification code from Step 1)
10

11
        # Parse the verified webhook event
12
        event = json.loads(body.decode('utf-8'))
13

14
        # Process webhook asynchronously (don't block the response)
15
        # This allows us to respond quickly to prevent unnecessary retries
16
        process_webhook_event(event)
17

18
        # IMPORTANT: Always respond with 201 to acknowledge receipt
19
        # Scalekit expects this response within 10 seconds
20
        return jsonify({'received': True}), 201
21

22
    except Exception as error:
23
        print(f'Webhook error: {error}')
24
        return jsonify({'error': 'Invalid signature'}), 401
25

26
def process_webhook_event(event):
27
    print(f'Processing event: {event["type"]}')
28

29
    event_type = event['type']
30
    event_data = event['data']
31

32
    if event_type == 'organization.directory.user_created':
33
        # Sync new user to your database
34
        handle_user_created(event_data)
35
    elif event_type == 'organization.directory.user_updated':
36
        # Update user profile in your database
37
        handle_user_updated(event_data)
38
    elif event_type == 'organization.directory.user_deleted':
39
        # Deprovision user from your application
40
        handle_user_deleted(event_data)
41
    elif event_type == 'organization.directory.group_created':
42
        # Handle new group creation
43
        handle_group_created(event_data)
44
    else:
45
        print(f'Unhandled event type: {event_type}')
46

47
def handle_user_created(data):
48
    # Use case: Sync new user to your database when provisioned via SCIM
49
    print(f'New user created: {data["email"]} in org: {data["organization_id"]}')
50

51
    # Sync to your database
52
    sync_user_to_database(data)
53

54
    # Grant default permissions
55
    setup_user_defaults(data['id'], data['organization_id'])

1
// Use case: Sync user data from directory to your application
2
// Examples: User provisioning, deprovisioning, group membership updates
3

4
package main
5

6
import (
7
    "encoding/json"
8
    "log"
9
)
10

11
type WebhookEvent struct {
12
    Type string                 `json:"type"`
13
    Data map[string]interface{} `json:"data"`
14
}
15

16
func handleWebhook(c *gin.Context) {
17
    // ... (verification code from Step 1)
18

19
    // Parse the verified webhook event
20
    var event WebhookEvent
21
    if err := json.Unmarshal(bodyBytes, &event); err != nil {
22
        c.JSON(http.StatusBadRequest, WebhookResponse{
23
            Error: &WebhookError{Message: "Invalid event format"},
24
        })
25
        return
26
    }
27

28
    // Process webhook asynchronously (don't block the response)
29
    // This allows us to respond quickly to prevent unnecessary retries
30
    go processWebhookEvent(event)
31

32
    // IMPORTANT: Always respond with 201 to acknowledge receipt
33
    // Scalekit expects this response within 10 seconds
34
    c.JSON(http.StatusCreated, WebhookResponse{
35
        Received: true,
36
    })
37
}
38

39
func processWebhookEvent(event WebhookEvent) {
40
    log.Printf("Processing event: %s", event.Type)
41

42
    switch event.Type {
43
    case "organization.directory.user_created":
44
        // Sync new user to your database
45
        handleUserCreated(event.Data)
46

47
    case "organization.directory.user_updated":
48
        // Update user profile in your database
49
        handleUserUpdated(event.Data)
50

51
    case "organization.directory.user_deleted":
52
        // Deprovision user from your application
53
        handleUserDeleted(event.Data)
54

55
    case "organization.directory.group_created":
56
        // Handle new group creation
57
        handleGroupCreated(event.Data)
58

59
    default:
60
        log.Printf("Unhandled event type: %s", event.Type)
61
    }
62
}
63

64
func handleUserCreated(data map[string]interface{}) {
65
    // Use case: Sync new user to your database when provisioned via SCIM
66
    log.Printf("New user created: %s in org: %s",
67
        data["email"], data["organization_id"])
68

69
    // Sync to your database
70
    syncUserToDatabase(data)
71

72
    // Grant default permissions
73
    setupUserDefaults(data["id"].(string), data["organization_id"].(string))
74
}

1
// Use case: Sync user data from directory to your application
2
// Examples: User provisioning, deprovisioning, group membership updates
3

4
package com.example.webhooks;
5

6
import com.fasterxml.jackson.databind.JsonNode;
7
import com.fasterxml.jackson.databind.ObjectMapper;
8

9
@PostMapping("/manage-users")
10
public ResponseEntity<Map<String, Object>> handleWebhook(
11
    @RequestBody String body,
12
    @RequestHeader Map<String, String> headers
13
) {
14
    try {
15
        // ... (verification code from Step 1)
16

17
        // Parse the verified webhook event
18
        ObjectMapper mapper = new ObjectMapper();
19
        JsonNode event = mapper.readTree(body);
20

21
        // Process webhook asynchronously (don't block the response)
22
        // This allows us to respond quickly to prevent unnecessary retries
23
        processWebhookEventAsync(event);
24

25
        // IMPORTANT: Always respond with 201 to acknowledge receipt
26
        // Scalekit expects this response within 10 seconds
27
        return ResponseEntity.status(201).body(Map.of(
28
            "received", true
29
        ));
30

31
    } catch (Exception error) {
32
        System.err.println("Webhook error: " + error.getMessage());
33
        return ResponseEntity.status(401).body(Map.of(
34
            "error", "Invalid signature"
35
        ));
36
    }
37
}
38

39
private void processWebhookEvent(JsonNode event) {
40
    String eventType = event.get("type").asText();
41
    JsonNode eventData = event.get("data");
42

43
    System.out.println("Processing event: " + eventType);
44

45
    switch (eventType) {
46
        case "organization.directory.user_created":
47
            // Sync new user to your database
48
            handleUserCreated(eventData);
49
            break;
50

51
        case "organization.directory.user_updated":
52
            // Update user profile in your database
53
            handleUserUpdated(eventData);
54
            break;
55

56
        case "organization.directory.user_deleted":
57
            // Deprovision user from your application
58
            handleUserDeleted(eventData);
59
            break;
60

61
        case "organization.directory.group_created":
62
            // Handle new group creation
63
            handleGroupCreated(eventData);
64
            break;
65

66
        default:
67
            System.out.println("Unhandled event type: " + eventType);
68
    }
69
}
70

71
private void handleUserCreated(JsonNode data) {
72
    // Use case: Sync new user to your database when provisioned via SCIM
73
    System.out.println("New user created: " + data.get("email").asText() +
74
        " in org: " + data.get("organization_id").asText());
75

76
    // Sync to your database
77
    syncUserToDatabase(data);
78

79
    // Grant default permissions
80
    setupUserDefaults(data.get("id").asText(), data.get("organization_id").asText());
81
}

Register the webhook in Scalekit dashboard
Section titled “Register the webhook in Scalekit dashboard”

Configure your webhook by specifying the endpoint URL, selecting events to receive, and setting up security.

In the Scalekit dashboard, navigate to Settings > Webhooks to register your endpoint.
- Click Add Endpoint and provide:
  - Endpoint URL - Your application’s HTTPS webhook handler (e.g., https://yourapp.com/webhooks/manage-users)
  - Description - Optional description for this endpoint
- Select which events you want to receive:
  - Directory sync events (organization.directory_enabled, organization.directory_disabled)
  - User events (organization.directory.user_created, user_updated, user_deleted)
  - Group events (organization.directory.group_created, group_updated, group_deleted)
- Copy the Signing Secret to verify webhook authenticity in your application
- Click Create
- Toggle Enable to activate the webhook
Complete webhook events reference View detailed schemas and payload examples for all webhook events
Test the webhook
Section titled “Test the webhook”

Use the Test tab in the Scalekit dashboard to verify your implementation before enabling it in production.
- Open the Test tab on the Webhooks page
- The left panel shows the request body sent to your endpoint
- Click Send Test Event to test your webhook handler
- The right panel shows your application’s response
- Verify your endpoint returns a 201 status code
For quick testing without deploying an endpoint, use a request bin service like Beeceptor or RequestBin. These services provide temporary endpoints that capture incoming requests and let you configure responses, making them ideal for webhook development and validation.
Local testing with ngrok
Test webhooks locally by exposing your development server using ngrok:
Terminal window
1 # Start your local server 2 npm run dev 3 4 # In another terminal, expose your local server 5 ngrok http 3000 6 7 # Use the ngrok URL in your Scalekit dashboard 8 # Example: https://abc123.ngrok.io/webhooks/manage-users
View webhook request logs
Section titled “View webhook request logs”

Scalekit keeps a log of every webhook request sent to your application and the response it returned. Use these logs to debug and troubleshoot issues.
- Navigate to Settings > Webhooks in your dashboard
- Select your webhook endpoint
- Click on the Logs tab to view request history
- Each log entry shows the request payload, response status, and timestamps
Requests and responses generated by the “Test” button are not logged. This keeps production logs free of test data.

Implement webhooks

Implementing webhooks

Verify the webhook request

Process the event and respond

Register the webhook in Scalekit dashboard

Test the webhook

View webhook request logs