Webhooks

Some endpoint requests may include an optional webhook parameter. If a webhook URL is specified in the request body of applicable endpoints, the system will make a single POST call to the specified URL with a JSON formatted body when the status of your request updates asynchronously. The JSON formatted body will contain identifying details about the initial request, such as cFiTransactionId and/or reference. It will also contain details about the current status of the request and any other relevant information.

Server Signature

Webhooks contain a server signature, "X-Signature", within the request headers. The "X-Signature" header value is calculated using an RSA-SHA256 signature algorithm, private key, and the webhook data contents in base 64 encoded format. The webhook also includes an "X-Token" header matching a webhook token configured specifically for the intended recipient (client). The webhook request body will contain the stringified JSON data object that was used in calculating the "X-Signature".

Checking Server Signature Example

It is up to the recipient (client) to ensure the validity of the webhook body contents by verifying the "X-Signature" value matches the data contents. Below is a code example demonstrating how to validate the signature of a received webhook. The contents of the webhook body, "data", are compared to the "X-Signature" value that was calculated using the same data. If successful, the data matches the signature and can be considered valid.

const crypto = require('crypto');
const fs = require("fs");

/*
"public.key" is assumed to be a file in the current folder containing the public webhook signature key
"data" is the stringified JSON formatted data contained in the body of the webhook
"receivedSignature" is the value of the "X-Signature" header of the webhook
*/

const publicKey = fs.readFileSync("public.key", "utf8");

const validateDigitalSignature = async (data, receivedSignature, publicKey) => {
    const verify = crypto.createVerify('RSA-SHA256');
    verify.update(data);
    return verify.verify(publicKey, receivedSignature, 'base64');
};

const dataIsValid = await validateDigitalSignature(data, receivedSignature, publicKey);

if (dataIsValid) {
    //do something with data
}

Public Key for Webhook Signature Validation

Please refer to the "Public Encryption Keys" section of the "Getting Started" section of this documentation for up to date public keys.