When receiving information from Currencycloud, it’s crucial that you trust its confidentiality and integrity.
This means you can be fully confident that we’re preventing sensitive information reaching the wrong people while making sure that it reaches the right people. All with the peace of mind that any information you receive from Currencycloud hasn’t been tampered with.
The introduction of message verification on our push notifications is the latest step in improving their integrity.
What is a push notification?
Currencycloud’s automated notifications capability gives users real-time visibility and instant updates on how transactions are progressing.
Our push notifications (webhooks) keep the user in the loop each step of the way. When the status of a transaction changes, a notification can be triggered to an end-point or email address of the client’s choice. Whether you’re using our APIs or Currencycloud Direct, it’s a really efficient way of keeping you, and your users, up to speed.
What is message verification?
Message verification will allow you to verify that a message originates from Currencycloud and has not been tampered with. We append a Hash-based Message Authentication Code (HMAC) to notifications, which you’ll be able to use to confirm the integrity of the message.
I’m a developer, how does it work and what do I need to know?
Step 1: Generate a secret key
A secret key that only you generate is shared between the message recipient (you) and the message sender (Currencycloud). You can create or refresh this randomly generated key via Currencycloud Direct or our API endpoint.
The ability to generate a secret key will be behind a new permission, so you can decide which contacts on your account can do this.
Step 2: Preparing the push notification
Using the secret key that only you know and the original message content, Currencycloud uses a strong hashing algorithm (SHA-512) to generate the HMAC. This code will be appended to any notification you receive, and using the same secret key and hashing algorithm you will be able to compute the HMAC. You can see an example below:
Step 3: Message verification:
When you receive the message, you’ll need to use the secret key, the message content and the same hashing algorithm (SHA-512) to compute the HMAC.
If the HMAC computed matches the one in the message header, then you’ve been able to cryptographically prove the authenticity of the message.
Please note: It is critical that you send the message content to the checksum validator exactly as it was received – for example, make sure no additional characters (e.g. white space or new lines) have been added.
How do I generate a secure key?
You will be able to generate a key via your ‘Profile page’ on our Direct platform. Alternatively, you can call the Generate HMAC Key API (/v2/contacts/generate_hmac_key). You’ll only be able to generate a secret key if the contact you’re logged in as has the correct permission – so get in touch with your Customer Success Manager to get this enabled. Generate a new secret key as often as you need to.
Where on the push notification do I see the HMAC?
The HMAC will be appended to the message header before it is delivered. You will not need to compute the HMAC to read the message content, only if you wish to verify its integrity.
How do I verify the HMAC?
To verify the integrity of a push notification, you’ll need to compute the hash of the message using the full content of the notification and your secret key, for example:
$ echo -n ‘<notification_content>’| openssl dgst -sha512 -hmac "My Secret Key" (stdin)= 8b472cf04424acd33c3e6e3e74a821929fda2511d034dcd992d3ef3009f9834bfd042d2215de1583c4d57b90a7299e3e9f765e1ec5de003b73d7666d8a284027
The result should be identical to the HMAC you received in the message header.