When we send an event notification (webhook) to your server, you must be able to verify that the:
-
Webhook genuinely came from us, not a malicious third party attempting to spoof our identity.
-
Data inside the webhook was not tampered with or altered while in transit over the internet.
To ensure webhook events are secure during transmission, we use key-pair authentication that includes a private and public key.
When a webhook is triggered, we generate a unique signature based on the payload and include it as an HTTP header. To ensure the request is authentic, validate this signature against your public key before processing the event. If the verification fails, reject the webhook.
The public key is the second half of the key pair and is safe to share publicly. You configure your receiving server to use this public key to mathematically check the signature attached to the incoming webhook.
Note
The public key must be manually refreshed on a regular basis. Failing to update this public key before expiration will result in immediate signature verification failures, causing you to miss critical event notifications.
If the public key successfully validates the signature, your application verifies that the payload was signed by our matching private key and that the data has not been changed. If the validation fails, the signature is invalid, and your system should securely reject the webhook.
For strict security compliance, cryptographic keys have a limited lifespan. We enforce a one-year expiration policy on key pairs. This is an industry-standard practice known as key rotation.
Keys must be rotated to:
-
Limit risk exposure. If a private key were ever compromised or accidentally exposed, an expiration date ensures that the compromised key has a limited window of usefulness for an attacker.
-
Maintain security standards. Regularly generating fresh key pairs protects your infrastructure against general advances in computing power that might weaken older cryptographic standards over time.
Because your application relies on the exact public key to verify incoming webhooks, always use the current and active public key. When our system automatically rotates the private key at the one-year expiration, the old public key immediately becomes obsolete.
To prevent your system from rejecting legitimate webhooks, you must manually retrieve the newly generated public key from our platform and update the configuration in your receiving endpoint. Failing to update this public key can result in signature verification failures, potentially causing missed event notifications.
To refresh a public key:
-
Sign in to Kount 360.
-
Select Admin.
-
Select Product Configuration.
-
Select Webhooks.
-
Select Refresh.
-
In the confirmation prompt, select Confirm to rotate your public key pair.
The public key is refreshed/rotated. The version number is updated with a new expiration date.
Comments
0 comments
Article is closed for comments.