Verifying signatures

What the signature contains

The 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 signature

Calculating 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.

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. 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)

3. 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.

4. Hash the check string with HMAC SHA256, using your notification secret. Example code to do this is shown below.

5. And then compare your signature to the value in the notification’s X-Volt-Signed header.

About test notifications

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 as follows:

{}|X-Volt-Timed|version

A quick example to test your HMAC Hashing

Using 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: 1631525064
• X-Volt-Signed: ed22494369277d25cf8c2293d142e5fddb9cecbea1f54e28ac16db0bee3b8009
• The complete, unmodified, body of the notification: {}
• Your notification secret: 9c0c8c97-c224-45ed-a195-23b54b1c67e5

Process

Concatenate the body, X-Volt-Timed and version using the pipe delimiter

{}|1631525064|1.0

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

ed22494369277d25cf8c2293d142e5fddb9cecbea1f54e28ac16db0bee3b8009

which should match the X-Volt-Signed key above.

Example code

Go

Code

package main

import (

"crypto/hmac"

"crypto/sha256"

"encoding/hex"

"fmt"

)

func main() {

check_string := hmac.New(sha256.New, []byte("9c0c8c97-c224-45ed-a195-23b54b1c67e5"))

check_string.Write([]byte("{}|1631525064|1.0"))

hmac := hex.EncodeToString(check_string.Sum(nil))

fmt.Println(hmac)

}

Output

ed22494369277d25cf8c2293d142e5fddb9cecbea1f54e28ac16db0bee3b8009

Java

Code

import java.io.UnsupportedEncodingException;

import java.math.BigInteger;

import javax.crypto.Mac;

import javax.crypto.spec.SecretKeySpec;

public class Main {

public static void main(String[] args) {

try {

byte[] hmacSha256 = HMAC.calcHmacSha256("9c0c8c97-c224-45ed-a195-23b54b1c67e5".getBytes("UTF-8"), "{}|1631525064|1.0".getBytes("UTF-8"));

System.out.println(String.format("%032x", new BigInteger(1, hmacSha256)));

} catch (UnsupportedEncodingException e) {

e.printStackTrace();

}

}

}

public class CalculateHMAC {

static public byte[] calcHmacSha256(byte[] secretKey, byte[] message) {

byte[] hmacSha256 = null;

try {

Mac mac = Mac.getInstance("HmacSHA256");

SecretKeySpec secretKeySpec = new SecretKeySpec(secretKey, "HmacSHA256");

mac.init(secretKeySpec);

hmacSha256 = mac.doFinal(message);

} catch (Exception e) {

throw new RuntimeException("Failed to calculate hmac-sha256", e);

}

return hmacSha256;

}

}

Output

ed22494369277d25cf8c2293d142e5fddb9cecbea1f54e28ac16db0bee3b8009

Perl

Code

use Digest::SHA qw(hmac_sha256_hex);

print(hmac_sha256_hex("{}|1631525064|1.0", "9c0c8c97-c224-45ed-a195-23b54b1c67e5"));

Output

ed22494369277d25cf8c2293d142e5fddb9cecbea1f54e28ac16db0bee3b8009

PHP

Code

<?

echo hash_hmac('sha256', '{}|1631525064|1.0', '9c0c8c97-c224-45ed-a195-23b54b1c67e5');

Output

ed22494369277d25cf8c2293d142e5fddb9cecbea1f54e28ac16db0bee3b8009

Python

Code

import hmac

import hashlib

print hmac.new(b'9c0c8c97-c224-45ed-a195-23b54b1c67e5', b'{}|1631525064|1.0', hashlib.sha256).hexdigest()

Output

ed22494369277d25cf8c2293d142e5fddb9cecbea1f54e28ac16db0bee3b8009

Ruby

Code

require 'openssl'

require "base64"

puts(OpenSSL::HMAC.hexdigest('sha256', "9c0c8c97-c224-45ed-a195-23b54b1c67e5", "{}|1631525064|1.0"))

Output

ed22494369277d25cf8c2293d142e5fddb9cecbea1f54e28ac16db0bee3b8009