Signing Keys

Overview

When we trigger a webhook or redirect a customer to you from Hosted Checkout or a 3D-Secure check we send you information about a transaction. For you to confirm the data integrity of that information we provide a hash of the data alongside it and secure it with a signing key. These signing keys are separate from your app_key (that you use for authentication) and are managed in the same place in the Hub.

Creating and activating a signing key

Signing keys can be configured from within the Hub:

1. Go to Settings menu and select the API Access tab.
2. Scroll to the Signing key section, select + Create Signing Key and enter a Name for your new signing key.
3. Click the Activate now checkbox to also activate the key you are creating.
4. If you forget to tick this you can activate the key from the Action menu in the list of keys by clicking ... then Set to active
5. Activating a new signing key will rotate your previous active signing key. This means it will be used alongside the new Active key to generate integrity checking hashes until it expires on the date and time shown in the Rotation ends column. After that point it will instead be Revoked and you will no longer be able to validate integrity with it.

Revoke a rotating signing key

Once you have updated your code to check integrity using your new Active signing key you may want to revoke the rotating key early as an extra security measure:

1. Go to Settings menu and select the API Access tab.
2. Scroll to the Signing key section
3. Find the key you want to revoke in the list of signing keys (it will be the only one showing a Rotating Status)
4. Open the Action menu for that key by clicking ...
5. Click Revoke key
6. Click Revoke to confirm you are no longer relying on this key for integrity checking and immediately revoke it

Edge cases your integrity check must consider:

Two hashes instead of one:

Note that you may receive two generated hashes instead of one. This will happen when you have both an active signing key and a rotating signing key and will result in the hash field containing both hashes separated by a comma. Your code should consider this when validating the hash and accept the payload as valid if either of the generated hashes matches your locally calculated hash value.

No hashes:

In some cases our backend services may not be able to retrieve a signing key to hash your payload with. This can happen:

• If you have never created a signing key and we haven't created one for you during your onboarding to our products
• Rarely, if a transient error happens that prevents the signing key from being retrieved at the time the webhook was triggered

If you receive an empty hash then you should call our GET /transactions/{transaction_id} endpoint with the transaction ID you received in your webhook payload to validate that the other fields are correct.

Migrating from app keys to signing keys

If you were using our products before signing keys were introduced (when your app_key was used to secure the hash) we will have automatically created an initial signing key for you that has the same value as your active app_key at the time of release. This means you can continue to validate your payloads with the same value you used to.