Verifying signatures
#
What the signature containsThe Volt signature is created by combining your notification secret with the body of the notification, and a timestamp. It won’t contain any useful, sensitive or personal information.
- On each notification request that we send you, we’ll include a custom HTTP header called X-Volt-Signed, which will contain the Volt signature.
#
How the signature works- You will get a POST message from Volt to your preconfigured notification URL.
- You’ll then need to calculate what you think the signature should be, based on the body of the notification itself and your notification secret.
- You’ll then check that the Volt signature you received in the X-Volt-Signed header of the notification matches the signature that you calculated.
- If they match, return an empty HTTP response with a status code of 200 (OK)
- If they don’t match, then you should return an empty HTTP response with a code of 400 (Bad Request) and do not process the notification.
#
Verifying the signatureCalculating the verification hash for a signature is based on three things, which are all included as part of the notification. Verification can be done in a few simple steps.
Extract the
User-Agent
,X-Volt-Timed
andX-Volt-Signed
headers and the ``body``` of the notification.From the User-Agent header, extract the notification
version
. The version 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)You'll then need to concatenate the notification body with the content of the X-Volt-Timed header and the version, using a pipe "|" delimiter (body|X-Volt-Timed|version) to create your check string.
Hash the check string with HMAC SHA256, using your notification secret. Example code to do this is shown below.
And then compare your signature to the value in the notification’s X-Volt-Signed header.
#
About test notificationsYour 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 as follows:
#
A quick example to test your HMAC HashingUsing some example values, let's run a quick test to make sure your signature check works as expected.
#
Example values- The
version
you extracted from the User-Agent: 1.0 X-Volt-Timed
: 1631525064X-Volt-Signed
: ed22494369277d25cf8c2293d142e5fddb9cecbea1f54e28ac16db0bee3b8009- The complete, unmodified,
body
of the notification: {} - Your
notification secret
: 9c0c8c97-c224-45ed-a195-23b54b1c67e5
#
ProcessConcatenate the body
, X-Volt-Timed
and version
using the pipe delimiter
Then, hash the concatenated string using SHA256 and your notification secret
, 9c0c8c97-c224-45ed-a195-23b54b1c67e5
. If everything is correct, you should get a computed HMAC of
which should match the X-Volt-Signed
key above.