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.
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
The Cardknox Gateway uses webhooks to send real-time notifications about transactions. To ensure the authenticity of these notifications and protect against DDoS attacks, a PIN can be set up in the Cardknox backend by a support representative.
Cardknox generates a unique signature to authenticate webhooks it sends, by:
- 1.Sorting the response parameters (key-value pairs) in alphabetical order based on the key name.
- 2.Extracting the values while preserving the order.
- 3.Appending the PIN to the string of values.
- 4.Hashing the string using the MD5 method.
The signature is included in the webhook header as
ck-signature. To verify the authenticity of the webhook on the recipient's end, the same steps used by Cardknox to generate the signature should be repeated, and the result should be compared to the "ck-signature" sent by Cardknox. If the two signatures match, it means that the webhook was indeed sent by Cardknox.Last modified 7mo ago