Webhooks

Cardknox accounts can be configured to send notifications, known as webhooks, to a designated URL each time a transaction is processed on the account. These webhooks are sent as a series of key-value pairs, encoded in a POST request, and contain all the necessary information to identify the transaction and its status. The information included in these webhooks can be customized to fit your needs, and a complete list of available fields can be found in the "Response Parameters" section. The webhook and optional pin can be enabled in the Cardknox Portal.

See example below:

Form values
xEnteredDate	9/3/2021 9:28:22 AM
xRefNum	506918667
xCommand	CC:Sale
xAmount	0.01
xResponseResult	Approved
xMaskedCardNumber	4xxxxxxxxxxx1111
xExp	1020
xCardType	Visa
xToken	7h39p8qp6hq2pgqp76mgg2qnq7npp3g5
xSoftwareName	KnockKnox
xSourceKey	Cardknox Support Key
xResponseBatch	6358090
xMerchantID	8663
xMerchantName	Cardknox Support

Raw Content

xEnteredDate=9%2f3%2f2021+9%3a28%3a22+AM&xRefNum=506918667&xCommand=CC%3aSale&xAmount=0.01&xResponseResult=Approved&xMaskedCardNumber=4xxxxxxxxxxx1111&xExp=1020&xCardType=Visa&xToken=7h39p8qp6hq2pgqp76mgg2qnq7npp3g5&xSoftwareName=KnockKnox&xSourceKey=Cardknox+Support+Key&xResponseBatch=6358090&xMerchantID=8663&xMerchantName=Cardknox+Support

Webhook PIN

For security purposes and to prevent DDoS attacks, a pin can be set up when configuring the webhook. Cardknox will generate a hash and it will be included in the webhook header as "ck-signature". To validate the authenticity of a webhook on the recipient's end, follow the steps below to generate a hash and compare it to the "ck-signature". If your hash matches the "ck-signature" it confirms that the webhook originated from Cardknox.

1. URL Decode Data: URL decode the webhook data.

2. Normalize Key Case: Convert all parameter keys to lowercase to ensure case-insensitive sorting.

3. Sort Data Alphabetically: Sort the parameters alphabetically by their keys.

4. Extract Values: Extract the values from the sorted parameters.

5. Concatenate Values with PIN: Combine the extracted values with the webhook pin at the end.

6. Hash Concatenated String Using MD5: Apply the MD5 hashing algorithm to the concatenated string.

Pin Rules

1. The pin can only be AlphaNumeric

2. The pin must be at least 15 characters long