Home › Gateway › Volt notifications › Signature verification

Signature verification

The Volt signature is created by combining your notification secret, the body of the notification, and a timestamp. It will never contain personal or sensitive information. Each notification that we send you will also include a custom HTTP header named X-Volt-Signed – which will contain the Volt signature.

How the signature works

  • You will receive a POST message from Volt to your preconfigured notification URL
  • Based on the body of the notification and your notification secret, you calculate what you think the signature should be
  • You then check your calculation against the signature received in the X-Volt-Signed to confirm they match

Verifying the signature

Calculating the verification hash for a signature is based on three things, all of which are included in the notification. To verify, follow these simple steps:

  1. Extract the User-Agent, X-Volt-Timed and X-Volt-Signed headers and the body of the notification
  2. From the User-Agent header, extract the notification version (this is the part after the forward Slash (/) and will be a numeric value. For example, if the User-Agent is Volt/2.0, the version is 2.0)
  3. Link the notification body with the content of the X-Volt-Timed header and the version, using the pipe delimiter | between them, like this: body|X-Volt-Timed|version. This creates your check string.

Please ensure you use the body exactly as we send it.  You shouldn’t expand escaped characters before calculating the signature.  

For example, we’ll send data with accented characters escaped like this "groupName":"Soci\u00e9t\u00e9 G\u00e9n\u00e9rale". If you convert it back to accented characters so you can read the groupName as "Société Générale" then you’ll end up with a signature that doesn’t match.

  1. Hash the check string with HMAC SHA256, using your notification secret (see below for an example)
  2. Finally, compare your HMAC signature to the value in the notification’s X-Volt-Signed header

Responding to notifications

Once you’ve compared your calculated HMAC signature to the one received with the notification, you should return one of two HTTP responses. 

  • If the signatures match, return an empty HTTP response with a status code of 200 (OK)
  • If they do not match, return an empty HTTP response with a code of 400 (Bad Request) and do not process the notification

Responding to tests

Your system should always be able to respond to a test notification and respond with a 200 (OK) status code. In the test notification, we’ll send an empty JSON object in the request body, so your check string should look like this:  

Test notification structure 
{}|X-Volt-Timed|version
Test notification example 
{}|12345678|2.0

We use test notifications to determine the health of your system.  If we stop sending you notifications because of failure, you’ll need to send and respond to a test notification before we start sending you other notifications again.

← Previous Volt notifications
Next → Testing notifications