Klevu Merchandising Webhook Integration Guide

Welcome to the Klevu Webhook Integration Guide! This guide explains how to integrate and validate webhooks sent by Klevu to your application. Webhooks allow your application to receive real-time updates from Klevu when specific events occur.

How It Works

Klevu sends a POST request to your configured endpoint whenever an event occurs. To ensure security, each request includes:

• X-KLEVU-HMAC: A cryptographic signature to verify the authenticity of the request.
• X-KLEVU-TIMESTAMP: A timestamp of when the request was generated, helping prevent replay attacks.
• X-KLEVU-APIKEY: Klevu apikey of the store.

You must verify the HMAC signature before processing the webhook.

Webhook Configuration

To configure a webhook in Klevu, contact Klevu Support with the following details:

Request Body Example

{
  "endpoint": "https://your-application-endpoint.com/webhook",
  "eventTypes": [
    "vm.default.rules"
  ],
  "apiKeys": [
    "klevu-16952739575191599",
    " ",
    "klevu-17183619175271599"
  ],
}

2. Verify HMAC Signature

To validate the request's authenticity:

1. Convert the request body into single line json(Minified) string.
   Example Minified JSON Output.

   {"id":"39f0290a-3eb1-4cec-a8fd-71a0792f3d15","apiVersion":"1.0","created":"2024-11-14T08:21:40.004166976","type":"vm.default.rules","apikey":"klevu-1719389107060243","data":{"payload":{"action":"UPDATE","eventObject":{"categories":[{"categoryPath":"automated collection"}]}}}}

   To minify or compress a JSON string to a single line, you can use various libraries depending on your programming language. 

   1. Use JSON Minifier by Code Beautify for a quick online solution.
2. Hash the resulting string using HMAC-SHA256 with rest auth key of the X-KLEVU-APIKEY.
3. Compare the computed hash with the value in the X-Klevu-HMAC header.

Example: HMAC Validation (Java)

   /**
     * Verifies the HMAC of a message using the provided secret and HMAC.
     *
     * @param requestBody       The original message (payload) whose HMAC needs to be verified.
     * @param restAuthKey       Refer the X-KLEVU-APIKEY and fetch rest auth key to compute the HMAC.
     * @param providedHmac      The HMAC received, which needs to be validated.
     * @throws Exception if an error occurs during HMAC computation.
     */
    public boolean verifyHmac(String requestBody, String restAuthKey, String providedHmac) throws Exception {
        // Initialize the HMAC-SHA256 Mac instance
        Mac mac = Mac.getInstance("HmacSHA256");
        SecretKeySpec secretKeySpec = new SecretKeySpec(restAuthKey.getBytes(), "HmacSHA256");
        mac.init(secretKeySpec);

        // Compute the HMAC for the given message
        byte[] computedHmacBytes = mac.doFinal(requestBody.getBytes());
        String computedHmac = Base64.getEncoder().encodeToString(computedHmacBytes);

        // Verify the computed HMAC against the provided HMAC
        if (providedHmac.equals(computedHmac)) {
            return true;
        } 
        return false;
    }

4. Webhook Request Structure

Below is an example of a webhook request sent by Klevu to your configured endpoint:

Webhook Request Example

{
  "id": "e00d94c1-bcb4-4ba9-93ac-cbf39ae37b41",
  "apiVersion": "1.0",
  "merchandisingVersion": 1741258873062,
  "created": "2024-11-08T05:29:54.272006888",
  "type": "vm.default.rules",
  "apikey": "klevu-17183619175271599",
  "data": {
    "payload": {
      "action": "UPDATE", 
      "eventObject": {
        "categories": [
          {
            "categoryPath": "10% off"
          }
        ]
      }
    }
  }
}

Supported Actions

Webhook Processing Details

• Batching of Categories:
  • To improve efficiency and scalability, Klevu webhooks will send up to 1000 categories per webhook call.
  • If more than 1000 categories are affected, multiple webhook calls will be made.

Testing Webhooks

Using Webhook.site

1. Register an endpoint on Webhook.site.
2. Update your Klevu webhook configuration with the generated endpoint URL.
3. Observe incoming requests and test validation logic.

Simulating Webhook Requests

1. Change any vm default rules in your store

Response Codes

Event Types

Below are the common event types supported by Klevu webhooks:

FAQs