Best Practices for Webhooks

Webhooks are HTTP endpoints that you register with a system, allowing that system to inform your application about events by sending HTTP POST requests with event information in the body.

Developers register their applications' webhook endpoints with Scalekit to listen to events from the directory providers of their enterprise customers. Here are some common best practices developers follow to ensure their apps are secure and performant:

Subscribe Only to Relevant Events

While you can listen to all events from Scalekit, it's best to subscribe only to the events your app needs. This approach has several benefits:

• Your app doesn't have to process every event
• You can avoid overloading a single execution context by handling every event type

Verify Webhook Signatures

Scalekit sends POST requests to your registered webhook endpoint. To ensure the request is coming from Scalekit and not a malicious actor, you should verify the request using the Signing Secret found in the Scalekit Dashboard > Webhook > Any Endpoint.

Here's an example of how to verify webhooks using the Svix library:

Webhook Signature Verification

Node.js

app.post('/webhook', async (req, res) => {
  // Parse the JSON body of the request
  const event = await req.json();

  // Get headers from the request
  const headers = req.headers;

  // Secret from Scalekit Dasbhoard > Webhooks
  const secret = process.env.SCALEKIT_WEBHOOK_SECRET;

  try {
    // Verify the webhook payload using the secret, headers, and event data
    await scalekit.verifyWebhookPayload(secret, headers, event);
  } catch (error) {
    // Return a 400 response if the signature is invalid
    res.status(400).json({ error: 'Invalid signature' });
  }
});

Python

from fastapi import FastAPI, Request

app = FastAPI()

@app.post("/webhook")
async def api_webhook(request: Request):
    body = await request.body()
    headers = {
        'webhook-id': request.headers.get('webhook-id'),
        'webhook-signature': request.headers.get('webhook-signature'),
        'webhook-timestamp': request.headers.get('webhook-timestamp')
    }
    print(
        scalekit.verify_webhook_payload(
            secret='<secret>', headers=headers, payload=body
        )
    )

  response = JSONResponse(status_code=201, content='')
    return response

Java

@PostMapping("/webhook")
public String webhook(@RequestBody String body, @RequestHeader Map<String, String> headers) {
  String secret = "<WEBHOOK SECRET>";
  boolean valid = scalekit.webhook().verifyWebhookPayload(secret, headers, body.getBytes());
  if (!valid) {
    return "error";
  }
  ObjectMapper mapper = new ObjectMapper();
  try {
    JsonNode node = mapper.readTree(body);
    String object = node.get("object").asText();
    JsonNode data = node.get("data");
    System.out.println("Object: " + object);
    System.out.println("Data: " + data);
    //business logic on data goes here
  } catch (IOException e) {
    return "error";
  }
  return "ok";
}

Check the Event Type Before Processing

Make sure to check the event.type before consuming the data received by the webhook endpoint. This ensures that your application relies on accurate information, even if more events are added in the future.

Node.js

app.post('/webhook', async (req, res) => {
  const event = req.body;

  if (event.type === 'scalekit.dir.user.create') {
    const { email, name } = event.data;
    await createUserAccount(email, name);
  }

  res.status(201).json({ status: 201 });
});

async function createUserAccount(email, name) {
  // Implement your user creation logic
}

Python

from fastapi import FastAPI, Request

app = FastAPI()

@app.post("/webhook")
async def api_webhook(request: Request):
    body = await request.body()
    event_type = json.loads(body.decode())['type']

    match event_type:
     case 'scalekit.dir.user.crete':
         print('create')
     case 'scalekit.dir.user.update':
         print('update')
     case _:
         print('No matching event found')

Java

@PostMapping("/webhook")
    public String webhook(@RequestBody String body, @RequestHeader Map<String, String> headers) {


        String secret = "<WEBHOOK_SECRET>";

        //verify webhook payload
        boolean valid  = scalekit.webhook().verifyWebhookPayload(secret,headers,body.getBytes());
        if (!valid) {
            throw new RuntimeException("Invalid signature");
        }
        ObjectMapper mapper = new ObjectMapper();
        JsonNode node;

        try {
            node = mapper.readTree(body);
        } catch (IOException e) {
            return "error";
        }

        String eventType = node.get("type").asText();
        switch (eventType) {
            case "scalekit.dir.user.create":
                // create a user
                break;
            case "scalekit.dir.user.update":
                // update a user
                break;
            default:
                System.out.println("Unknown event type");
        }

  return "ok";
}

Avoid Webhook Timeouts

To avoid unnecessary timeouts, respond to the webhook trigger with a response code of 201 and process the event asynchronously.

By following these best practices, you can ensure that your application effectively handles events from Scalekit, maintaining optimal performance and security.