Webhooks

Webhooks are implemented to notify the customer when their onboarding is complete.

Webhooks #

A webhook is a functionality provided by an API (Application Programming Interface) that allows applications to receive real-time data by sending HTTP requests to a specified URL when certain events occur. In our solution it is to notify the customer when their onboarding is complete.

Webhook definition #

Webhook parameters should be defined in Integration-Webhooks section of Trusthub Customer Dashboard. There are 2 parameters:

• Webhook URL - the url that will listen for notifications (must be https);
• Onboarding result. It is possible to define a separate endpoint for each status or to send all onboarding statuses to the same endpoint. There are following statuses:
  • Auto approved
  • Manual approved
  • Waiting for manual approve
  • Auto rejected
  • Manual rejected
  • Session initialized (the /initialize endpoint was called).
  • Session started (the user has started the session).

Session started

Webhook attributes #

Each webhook delivers following fields:

Webhook sample

{
  "sessionId": "e7abc715e-a674-48ef-a237-1196ab3664e8",
  "status": "AUTO_APPROVED",
  "projectId": "development",
  "externalId": "53421526A"
}

Webhooks Validation #

Every webhook request comes with an X-Signature attribute in the request headers. This X-Signature is in base64 and is formed via HMAC-SHA256, employing your API password to sign the response data. To ensure the webhook reply is genuine, replicate the signature creation process and make sure the signature you produce is identical to the one that was included with the request.

Webhook sample

{"X-Signature":"dBHQScfZMdbIxq+8UaPe9TdGz/yX9C1uLugLp0j1RLI=","X-Signature-Algorithm":"HMAC-SHA256"}

JavaScript code sample for validating signatures. Please refrain from storing secrets directly in production code!

const crypto = require('crypto');
// Provided request body
const requestBody =
    '{"sessionId":"186e4aaa-95f5-461d-9ff1-837bf1484b10","externalId":"external code 123","projectId":"test-project","status":"AUTO_APPROVED"}';
// The secret key used for hashing
const secretKey = '<secret>';
// The expected (provided) signature
const expectedSignature = '<returned by API>';
// Verify the signature using HMACSHA256 and return true if it matches the provided signature
function verifySignature(content, secretKey) {
    const hmac = crypto.createHmac('sha256', secretKey);
    hmac.update(content);
    const computedSignature = hmac.digest('base64');
    return computedSignature === expectedSignature;
}
// Check if the signature is valid
if (verifySignature(requestBody, secretKey)) {
    console.log("Webhook received and verified.");
} else {
    console.log("Invalid signature.");
}