Webhooks

📘
What are Webhooks?
Webhooks allow interaction between web-based applications through the use of custom callbacks. The use of webhooks allows web applications to automatically communicate with other web-apps. Unlike traditional systems where one system (subject) keeps polling another system (observer) for some data, Webhooks allow the observer to push data into the subject’s system automatically whenever some event occurs.
This eliminates the need for constant checking to be done by the subject. Webhooks operate entirely over the internet and hence, all communication between systems must be in the form of HTTP messages

In the below sections you will find all that you may need to get started on implementing Webhooks for your Merchant with Ecentric.

The webhook functionality is provided to merchants to be able to subscribe to transaction events. The webhook will be triggered upon completion of a transaction.

Webhook Setup

Create a HTTP REST webhook endpoint.
Handle the request and return a 200 HTTP response code.
Ensure that your webhook endpoint is publicly available over HTTPS.
Share the webhook endpoint URL with Thumbzup in order to have it configured.
If you would like to verify the signature share a secret with Thumbzup or request one to be generated for you.

Important setup values

Name	Example	Description
URL	https://example.com/my/webhook/endpoint	The URL of the webhook endpoint.
Secret Key	T8ug/XtrZehltMPH4pwXK+l8WE9FaCSLmGYa8*ge	The secret key is used to verify the signature that Thumbzup will send in the header. (x-signature) The secret key can be generated by Thumbzup OR the Merchant.

Consuming the Webhook

A webhook gets triggered when a transaction has been completed from a merchant terminal. The webhook should be setup correctly and flagged as active.
The transaction data is sent in the request body.
Ecentric signs the webhook events it sends to your endpoints by including a signature in each event’s x-signature header. This allows you to verify that the events were sent by Thumbzup. You can verify signatures by following the example code.

POST

Parameter	Value
Header	x-signature
Query Parameters	v (the version set in the webhook config)

The below code is a sample of the Webhook request body

{
    "authCode":"335668",
    "transactionDateTime":1680692183394,
    "txResultCode":"00",
    "panWithBin":"448381** **** 6065",
    "tsi":"E800",
    "merchantName":"Kurts Nice Store",
    "rrn":"309556220002",
    "transactionType":"DEBIT_GOODS_AND_SERVICES",
    "transactionUUID":"a2bc5b1e-e898-43dc-a0ba-ca526842f9c7",
    "tvr":"0880008000",
    "applicationLabel":"Visa Card  ",
    "merchantId":"910000000002222",
    "transactionAmount":60000,
    "cvm":"PIN Verified",
    "isApproved":true,
    "aid":"A0000000031010",
    "batchNumber":"0"
}

Example Java code to extract and verify the signature

package org.example;

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.security.GeneralSecurityException;
import java.security.InvalidKeyException;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.Base64;

import static java.lang.System.out;
import static java.nio.charset.StandardCharsets.UTF_8;

class Main {
    public static void main(String[] args) throws GeneralSecurityException {

        var signingAlgo = "HmacSHA256";
        var secretKey = "LTcwMDI0Ok9ubGluZSBwcm9jZXNzIGVycm9y";

        var requestBody = """
            {
                "authCode":"335668",
                "transactionDateTime":1680692183394,
                "txResultCode":"00",
                "panWithBin":"448381** **** 6065",
                "tsi":"E800",
                "merchantName":"Kurts Nice Store",
                "rrn":"309556220002",
                "transactionType":"DEBIT_GOODS_AND_SERVICES",
                "transactionUUID":"a2bc5b1e-e898-43dc-a0ba-ca526842f9c7",
                "tvr":"0880008000",
                "applicationLabel":"Visa Card  ",
                "merchantId":"910000000002222",
                "transactionAmount":60000,
                "cvm":"PIN Verified",
                "isApproved":true,
                "aid":"A0000000031010",
                "batchNumber":"0"
            }
            """.trim();

        var requestSignatureHeader = "1EhcAU3KMdk203eBC4fiXeQt/vY1vSXGiND2adUFRM4=";

        var isSignatureValid = verifyHmac(
                requestBody.getBytes(),
                Base64.getDecoder().decode(requestSignatureHeader),
                secretKey.getBytes(),
                signingAlgo);

        if (isSignatureValid) {
            out.println("IS VALID");
        } else {
            out.println("IS NOT VALID");
        }
    }

    public static boolean verifyHmac(byte[] message, byte[] hmacSignature, byte[] secretKey, String algorithm) {

        try {
            var signingKey = new SecretKeySpec(secretKey, algorithm);
            var mac = Mac.getInstance(algorithm);
            mac.init(signingKey);

            var calculatedSignature = mac.doFinal(message);

            return MessageDigest.isEqual(calculatedSignature, hmacSignature);

        } catch (NoSuchAlgorithmException | InvalidKeyException e) {
            e.printStackTrace();
            return false;
        }
    }
    
    public static String generateWebhookHmacSignature(String webhookPayload, String webhookSecreteKey) throws GeneralSecurityException {

        byte[] hmacData;
        var algo = "HmacSHA256";
        var secretKey = new SecretKeySpec(webhookSecreteKey.getBytes(UTF_8), algo);
        var mac = Mac.getInstance(algo);

        mac.init(secretKey);
        hmacData = mac.doFinal(webhookPayload.getBytes(UTF_8));

        return Base64.getEncoder().encodeToString(hmacData);
    }
}

In the section you will find examples of the types Webhooks that are currently supported by Ecentric Payment Sytems.

Examples of Webhook Types

PilotPOS Webhook:

This webhook type is specific to Pilot Point Of Sale Software and Webhook events will only be sent on Approved transactions.

Below is a list of Commands that will trigger a webhook event:

TRANSACTION_CONFIRMATION,
TRANSACTION_REVERSAL,
TRANSACTION_DECLINE,
TRANSACTION_DECLINED_ABORT,
TRANSACTION_REFUND,
CNP_REFUND,
PRE_AUTH_TRANSACTION,
PRE_AUTH_INCREMENTAL,
PRE_AUTH_CANCELLATION,
PRE_AUTH_CONFIRMATION,
PRE_AUTH_COMPLETION,
PRE_AUTH_CANCELLATION_CONFIRMATION

Transaction Status Webhook:

Generic webhook for consumers to know about the status of a transaction according. This Webhook will send events on all approved, declined, and failed transactions.

Below is a list of Commands that will trigger a webhook event:

TRANSACTION_CONFIRMATION,
TRANSACTION_REVERSAL,
TRANSACTION_DECLINE,
TRANSACTION_DECLINED_ABORT,
TRANSACTION_REFUND,
CNP_REFUND,
PRE_AUTH_TRANSACTION,
PRE_AUTH_INCREMENTAL,
PRE_AUTH_CANCELLATION,
PRE_AUTH_CONFIRMATION,
PRE_AUTH_COMPLETION,
PRE_AUTH_CANCELLATION_CONFIRMATION);

Settlement Webhook:

This Webhook is specific to Absa Markoff file processing. An event will only be sent when a markoff file must be sent to ABSA for processing.

📘What are Webhooks?