Sentiments Realtime Webhook Implementation¶

Overview¶

Sentiments Webhook feature can be used to notify Sentiments feedback records to any external webhook endpoint. This feature allows you to automate the Sentiment feedback records receiving process by any external fault management or case management system.

Exposing a Webhook Endpoint¶

A webhook endpoint is often simply referred to as a webhook. It is a URL provided by a web service or application where data is sent automatically in real-time when a certain event occurs. So to automatically receive Sentiment feedback records on your fault management or case management system you should have a webhook endpoint available in your application that can accept below provided JSON data block.

Sample Sentiment feedback:¶

    {
        "transaction_id": "ef9a847c-b6e5-41de-b15a-bce582036c51",
        "report_suite_id": "wogaastagingwogaacloudprod",
        "country": "SG",
        "rating": 6,
        "page_url": "https://staging.wogaa.cloud/sentiments/info-svcs/427/configure/notification",
        "browser_version": "Chrome 126",
        "browser_type": "Chrome",
        "device_type": "Desktop",
        "os_version": "Mac OS >=10.15.7",
        "responses": [
            {
                "response": "test@test.com",
                "questionNumber": "1",
                "question": "Your email"
            },
            {
                "response": "test should not receive",
                "questionNumber": "0",
                "question": "What did you like most??"
            }
        ],
        "createdAt": 1721725925688
    }

Configuration¶

Webhook endpoint configuration on WOGAA is available under Information Service Configuration -> Notifications -> Webhook as shown below.

• First you have to obtain your webhook endpoint's publicly accessible URL and update it in the 'Enpoint URL' text box.
• Once you press Save button you will receive an email with an attachment containing the secret key which is used to verify the authenticity of the data you receive via the webhook endpoint. Please refer to 'Implementing Signature Verification' to understand how to build this mechanism.
• Once you have successfully updated the secret key on your application you may switch 'Enable Webhook' to start receiving Sentiments feedback records on your fault management or case management system.

Implementing Signature Verification¶

Sentiments webhook notification system is using a security feature for the integrated fault management or case management systems to verify the feedback records they receive are correct and what exactly WOGAA has sent out. So to build this feature WOGAA is using a SHA256 signature verification mechanism. You may find the SHA256 signature for each of the received Sentiments feedback notification in the 'WOGAA-Signature' HTTP header value.

How to Verify SHA256 Signature¶

1. Generate the SHA256 signature for the received payload on your webhook. You may find a sample code snippet below to generate the SHA256 signature on your received payload.
2. Get the received SHA256 signature from the 'WOGAA-Signature' HTTP header value and compare it with the SHA256 signature you have generated in step #1.
3. If the two SHA256 signatures match, your received payload is good to process.

Sample Code Snippet to Verify SHA256 Signature¶

    const body = '[RECEIVED_PAYLOAD]';
    const bodyStr = JSON.stringify(body);
    const requestSignature = '[RECEIVED_SHA256_SIGNATURE]';
    const webhookSecret = '[WEBHOOK_SECRET_RECEIVED_BY_EMAIL]';

    const hmac = crypto.createHmac("sha256", webhookSecret);
    const trustedSig = Buffer.from(
        hmac.update(bodyStr).digest("hex"),
        "utf8",
    );

    const untrustedSig = Buffer.from(requestSignature || "", "utf8");
    if (trustedSig.length == untrustedSig.length && crypto.timingSafeEqual(trustedSig, untrustedSig)) {
        console.log('Signature verification successful');
    }
    else {
        console.log('Signature verification failed');
    }