Working with webhooks

Registering your endpoints

To receive webhook events, you will need to register your endpoint with us.

1. Contact Us: Reach out to us over the dedicated Slack channel or email our support team at developers@kota.io with the subject “Webhook Endpoint Registration.”
2. Provide Details:
   • Endpoint URL: The URL to receive events (e.g., https://example.com/webhooks/receive).
   • Event Types: List the events you want to receive or request all.
3. Confirmation: Once processed, we’ll confirm the registration and provide the webhook secret key.

Creating a webhook handler

A webhook handler is responsible for receiving and processing the events sent from our system to your specified URL. This section will guide you through the steps needed to create a webhook handler using Node.js that can successfully receive, validate, and respond to our webhook events. This should be no different in any other framework or language.

API endpoints for registering and managing webhook endpoints coming soon

Endpoint Setup

Start by setting up an endpoint in your Node.js application using a framework like Express to handle incoming POST requests. This endpoint will receive the webhook payload as an HTTP request, which will be in JSON format.

1
const express = require('express');
2
const app = express();
3
app.use(express.json());  // Middleware to parse JSON
4
5
app.post('/webhooks/receive', (req, res) => {
6
    const payload = req.body;
7
    
8
    // TODO: Add your processing logic here
9
    
10
    res.status(200).send();
11
});
12
13
app.listen(3000, () => {
14
    console.log('Webhook handler is running on port 3000');
15
});

Ensure the endpoint responds with a 2xx HTTP status code if the payload is received and processed successfully. If there are any issues, return an appropriate error code (e.g., 400 for validation errors, 500 for server issues). If a non 2xx status code is returned, we will not retry the delivery of the event.

Receiving the webhook payload

The webhook payload will contain relevant event data in JSON format. You will need to extract this data from the request body.

Example employee.created event payload:

1
{
2
"id": "evt_d3491808363d4dc79d15f5ced0035cc4",
3
"type": "employee.created",
4
"platform_id": "pt_f57c25e3d975453cabeb9be650f2254c",
5
"data": {
6
    "id": "ee_af6601bea10d4bcba95e4a2f40f2ae14",
7
    "platform_id": "pt_f57c25e3d975453cabeb9be650f2254c",
8
    "employer_id": "er_r879d5e3d975453cabeb9be650f22345",
9
    "status": "pending",
10
    "external_customer_id": "cust_001",
11
    "first_name": "John",
12
    "last_name": "Doe",
13
    "date_of_birth": "1985-01-01",
14
    "sex_at_birth": "male",
15
    "home_address": {
16
    "line1": "123 Main St",
17
    "city": "Anytown",
18
    "state": "NY",
19
    "postal_code": "12345",
20
    "country_code": "US"
21
    },
22
    "nationality": "US",
23
    "start_on": "2023-01-01",
24
    "phone_number": "+1234567890",
25
    "email": "john.doe@example.com",
26
    "offboard_on": "2024-01-01",
27
    "object": "employee"
28
},
29
"created_at": "2023-01-01T00:00:00Z",
30
"api_version": "1.0",
31
"object": "event"
32
}

For the example employee.created event:

• The id starts with the prefix evt_.
• The type is employee.created.
• platform_id identifies the platform in our system.
• created_at remains unchanged on retries.
• api_version is “1.0”, aligned with our API version.
• The object field in the root payload is “event”, while in the data field it is “employee”.
• The data object mirrors the structure of the GET Employee API response, allowing easy reuse of models between webhook and API responses.

Example (in Node.js)

1
app.post('/webhooks/receive', (req, res) => {
2
    const { id, type, platform_id, data, created_at, api_version, object } = req.body;
3
4
    // Process the event data
5
    console.log(`Received event: ${type} with ID: ${id}`);
6
    
7
    res.status(200).send('Webhook received');
8
});

Validating the webhook payload

Before processing the webhook, it is important to verify the authenticity of the request. This is done by validating the x-kota-webhook-signature header that accompanies the request. The header contains a timestamp and a signature, which you can use to confirm that the payload has not been tampered with.

The HTTP header looks like this:

1
x-kota-webhook-signature: t=1726507206,v1=e5757080c0fd1494a8395621ee708827180afbf10e2f5fba355faa925bf8ea7b

It includes:

• t (timestamp): The time at which the signature was generated.
• v1 (signature): The HMAC SHA-256 signature, computed using your webhook secret.

You can verify the signature by following these steps:

1. Extract the t (timestamp) and v1 (signature) from the x-kota-webhook-signature header.
2. Construct a message string by concatenating the timestamp and the request body, separated by a dot (.).
3. Use your webhook secret to compute the HMAC SHA-256 hash of the message.
4. Compare the computed hash with the provided v1 signature. If they match, the request is valid.

Here’s how to implement signature verification in Node.js:

1
const crypto = require('crypto');
2
3
function verifySignature(headerSignature, secretBase64, payload) {
4
    // Split the signature header into timestamp and signature parts
5
    const [timestampPart, signatureVerification] = extractSignatureParts(headerSignature);
6
7
    // Decode the secret from Base64
8
    const secretBytes = Buffer.from(secretBase64, 'base64');
9
10
    // Create the message string for HMAC hashing
11
    const message = `${timestampPart}.${payload}`;
12
    const messageBytes = Buffer.from(message, 'utf8');
13
14
    // Compute the HMAC hash using the secret
15
    const hash = crypto.createHmac('sha256', secretBytes).update(messageBytes).digest('hex');
16
17
    // Compare the computed signature with the provided signature
18
    return hash === signatureVerification;
19
}
20
21
function extractSignatureParts(headerSignature) {
22
    // Example header format: t=timestamp,v1=signature
23
    const signatureParts = headerSignature.split(',');
24
    const timestampPart = signatureParts[0].split('=')[1].trim(); // Extract timestamp
25
    const signatureVerification = signatureParts[1].split('=')[1].trim(); // Extract signature
26
    return [timestampPart, signatureVerification];
27
}
28
29
// Example usage:
30
app.post('/webhooks/receive', (req, res) => {
31
    const headerSignature = req.headers['x-kota-webhook-signature'];
32
    const secretBase64 = 'your-base64-encoded-secret'; // Replace with your actual secret
33
    const payload = JSON.stringify(req.body); // The request body as a string
34
    
35
    if (verifySignature(headerSignature, secretBase64, payload)) {
36
        // Process the webhook payload
37
        res.status(200).send();
38
    } else {
39
        res.status(401).send('Invalid signature');
40
    }
41
});

• The verifySignature function takes the x-kota-webhook-signature header, your secret key (in Base64), and the payload. It generates a HMAC-SHA256 hash using the secret and compares it with the signature provided in the header.
• The extractSignatureParts function parses the header to extract the timestamp (t=…) and the signature (v1=…).
• If the computed signature matches the one in the request, the webhook is valid.

This ensures that only requests from your trusted source are processed, protecting your application from tampered or spoofed payloads.

Event delivery

Webhook events are delivered instantly upon trigger. If your system responds with a successful 2xx status code, no further retries will be made. However, if the event is not acknowledged, retries will follow based on a backoff schedule.

Successful delivery

A successful delivery occurs when your webhook endpoint returns any 2xx HTTP status code. This confirms that the event was received and processed correctly. Upon receiving a successful response, no retries will be attempted for that event.

Retry Behaviour

In the event that a webhook cannot be delivered successfully (i.e., your endpoint does not return a 2xx HTTP status code), our system will retry the delivery according to an exponential backoff strategy in 9 attempts over 3 days.

The retries are spread out over a period of time to accommodate temporary issues such as network disruptions or service downtime on your end. Additionally, a random jitter of ±15 seconds is applied to each retry to prevent simultaneous retries from overloading your server.

The retry process will stop if your endpoint returns a 2xx status at any point, indicating successful delivery. If the event is not acknowledged after the final attempt, no further retries will be made.

Missed retry behaviour

If the final retry attempt fails, we will notify you via email to alert you of the undelivered event. You should manually process these events within 30 days of the initial event trigger to ensure no data loss.

Event delivery order

Webhook events are delivered as soon as they occur but we do not guarantee their delivery in a strict chronological order. Ensure your system can handle events arriving out of sequence by using timestamps or unique IDs to process them correctly.

Versioning

Our API currently uses version 1.0, which is specified in both the API and webhook payloads. Each webhook event includes the api_version field, which is set to “1.0”. This ensures that the data format and behavior you receive aligns with version 1.0 of our API.

Example webhook payload:

1
{
2
"id": "evt_cd7dc78d47374cf6af676d95256c0153",
3
"api_version": "1.0",
4
"type": "employee.created",
5
"platform_id": "pt_fe914e5b13564f26ad715821e8e3dfaa",
6
"object": "event",
7
"created_at": "2023-01-01T00:00:00Z",
8
"data": { ... }
9
}

Staying up to date

To ensure compatibility, we recommend monitoring our announcements and documentation for new versions and their features. Ensure that your system calls the API with the correct version based on the version of the webhook you are using. The version of the webhook is also the version of the API that the webhook is using.

Best practices

To ensure secure and reliable handling of webhook events, follow these best practices:

• Validate Signatures: Always verify the x-kota-webhook-signature to ensure requests are authentic.
• Use HTTPS: Protect data in transit by serving your webhook endpoint over HTTPS.
• Idempotency: Implement logic to handle duplicate events, ensuring each event is processed only once.
• Respond Quickly: Aim to return a 2xx response within a few seconds to avoid unnecessary retries.
• Rate Limiting: Prepare your system to handle high volumes of events efficiently, including potential bursts.