Overview

10min

Webhook events are sent during a Link session as the end user interacts with the application. You can track progress through this session( linkId ), get information about end user usage, and receive notifications when certain processes are complete.
Whether you integrate through WhiteLabel or API Only, some API statuses will also be sent to you via webhook.
You can also choose to turn off or turn on the above two types of webhooks in the Console.
Only when enabled, will you be asked to configure a webhook address and send corresponding the event to the webhook.
﻿
Based on the regulatory and compliance requirements of the Open finance, we have launched specific data products for regulated financial institutions (FI). Please select the following specific method based on whether your company is regulated by the central bank or Open finance.
How to use webhook
Register
When you are ready to go live and move your application to production, you can obtain the accessKey and secretKey for production environment through Klavi business personnel([email protected]) or Klavi console, and set your webhook URL. 
Klavi defaults to using the secretkey and SHA-256 HMAC algorithm to sign the payload.
Retry logic
If we get a 2xx response from your webhook listener server, the webhook event is registered as a success. For any non-200 HTTP status code (failed event), we will resend the webhook.
Default retries configurations:
Timeout: 10s
Retries: 5
Backoff for automatic retries: 250ms Exponential
Max redirects: 3
Payloads
The following parameter will be included in the request header that Klavi POST to you, otherwise it will not be present.
Headers
Text
x-klavi-signature: 'webhook-hmac-hash'
x-klavi-timestamp: '123456789012'
x-klavi-signature: 'webhook-hmac-hash'
x-klavi-timestamp: '123456789012'
﻿
Event body
Name
Description
partnerAppId
Unique identifier for partner
eventId
Unique identifier for the event
eventType
api: All events related to API call
eventName
The name of each event
eventTime
The time when this event was triggered(UTC timezone)
payload
All events include a wrapper that contains metadata. The event data is within the this key, different events result in different payload contents.
externalInfo
If you specified custom events via the externalInfo parameter when generating a links, you will receive the object( externalInfo ) back in the body for all other link event type
Example: Pass the externalInfo object in a generate links call to receive the started event notification.
JSON
"externalInfo": {
  "myCustomerId": "123456789",
  "myRequestId": "234567890"
}
"externalInfo": {
  "myCustomerId": "123456789",
  "myRequestId": "234567890"
}
﻿
After the link is successfully created, the parameters you pass will be returned to you through webhook.
In order to improve the system performance of both parties, Payload uses array objects, which means multiple events may be merged into one JSON and sent to you.
JSON
[
    {
        "partnerApp":"12345678",
        "eventId":"1495468585434-0e73d1719173766fe4dfe1a8",
        "eventType":"api",
        "eventName":"link-created",
        "eventTime":"2021-05-21T08:30:00Z",
        "payload":{
            "linkId":"ed812-81fcec-7ec55-7aa7d29-2a3188b75"
        },
        "externalInfo":{
            "myCustomerId":"12345678",
            "myRequestId":"23456789"
        }
    }
]
[
    {
        "partnerApp":"12345678",
        "eventId":"1495468585434-0e73d1719173766fe4dfe1a8",
        "eventType":"api",
        "eventName":"link-created",
        "eventTime":"2021-05-21T08:30:00Z",
        "payload":{
            "linkId":"ed812-81fcec-7ec55-7aa7d29-2a3188b75"
        },
        "externalInfo":{
            "myCustomerId":"12345678",
            "myRequestId":"23456789"
        }
    }
]
﻿
HMAC Verification
If you’re using webhooks for sensitive or critical information, we recommend that you verify the signature of the webhook.

Tips for Best Practice:
1
Create a SHA-256 HMAC of the request body using your secretKey as the key
2
Compare it to the signature included on the x-klavi-signature header. If the two are equal then the request is valid, otherwise, it is spoofed.
3
Store the eventId and ignore webhooks with an ID that have already been processed to prevent replay attacks.
The x-klavi-signature and x-klavi-timestamp header gets added to every event sent.
﻿
Here is an example of signature verification in NodeJS:
Node.js
const crypto = require('crypto');
const partnerSecret = '{{SECRET-KEY}}';
router.use('/webhook-handler', (request, res) => {
  const body = request.body;
  const signature = crypto
    .createHmac('sha256', partnerSecret)
    .update(JSON.stringify(body))
    .digest('hex');

  if (request.get('x-klavi-signature') !== signature) {
    throw new Error('Spoofing detected, rejecting webhook');
  }
});
const crypto = require('crypto');
const partnerSecret = '{{SECRET-KEY}}';
router.use('/webhook-handler', (request, res) => {
  const body = request.body;
  const signature = crypto
    .createHmac('sha256', partnerSecret)
    .update(JSON.stringify(body))
    .digest('hex');

  if (request.get('x-klavi-signature') !== signature) {
    throw new Error('Spoofing detected, rejecting webhook');
  }
});
﻿
﻿

Name	Description
partnerAppId	Unique identifier for partner
eventId	Unique identifier for the event
eventType	api: All events related to API call
eventName	The name of each event
eventTime	The time when this event was triggered(UTC timezone)
payload	All events include a wrapper that contains metadata. The event data is within the this key, different events result in different payload contents.
externalInfo	If you specified custom events via the externalInfo parameter when generating a links, you will receive the object( externalInfo ) back in the body for all other link event type

Updated 29 Sep 2024

Did this page help you?

Overview

API Events