Securing Your Webhooks

The option of securing your Caspeco webhooks is available by creating a signature on the webhook page in Caspeco Cloud. The signature allows you to verify that the webhook messages that are being received by your receiving endpoint actually comes from Caspeco.

Creating Your Signature

To create your signature, head to Settings > Webhooks > Create signature and click on the “Generate”-button. Once the signature has been created you can copy it and use it to secure your webhooks from potential attacks by the verification steps described below.

Verifying Your Signature

The Caspeco-Webhooks-Signature header contains a Unix timestamp which is prefixed by t= and the signature itself which is prefixed by s=. The signatures are generated by using a hash-based message authentication code (HMAC) with a SHA-256 hash.

Extraction of Timestamp and Signature

Split the header using “,” as a separator to get a list of elements. Then divide the elements using the “=” character to get value and prefix pairs.

Preparing the “signed_payload” String

Once the values have been separated you can generate your signed_payload string by concatenating the timestamp + “.” + the payload JSON-body.

Get the Expected signature

Create an HMAC with the SHA-256 hash algorithm function. Use the signing secret as key and the generated signed_payload as message.

ComputeSignature(stringToSign, key)
{
  using (var hmacsha256 = new HMACSHA256(Convert.FromBase64String(key)))
  {
    var bytes = Encoding.UTF8.GetBytes(stringToSign);
    var hashedBytes = hmacsha256.ComputeHash(bytes);
    return Convert.ToBase64String(hashedBytes);
  }
}

Compare the Signatures

Compare the signature in the header to your expected signature. If you wish to perform and equality match to protect yourself from replay-like attacks, compute the difference between the current and received timestamps to decide if the difference is within your tolerance range.