Signature Validation

Ensuring the security and integrity of your data is paramount. To this end, when interfacing with Help Scout, whether through callback URLs or when utilizing the Side Panel, you have the ability to verify whether requests sent to your application truly originate from Help Scout. This is achieved through the process of calculating a digital signature.

Each request Help Scout sends, be it to the main content callback URL or to the Side Panel’s URL, includes an X-HelpScout-Signature query parameter. This signature contains a calculated value derived from a secret key and the remaining request’s query parameters.

To verify whether the request came from Help Scout, follow these steps:

  1. Compute an HMAC hash using the secret key and the remaining query parameters from the request. It is essential to remove the signature itself as well as any parameters that were originally part of your application’s URL.

  2. Compare the calculated hash value to the value contained in the X-HelpScout-Signature query parameter of the request.

If the computed hash and the signature value match, you can confidently determine that the request was sent from Help Scout.

Here is an example of how this implementation could look like in PHP:

<?php
define('APP_SECRET_KEY', 'my-secret-key');

function isFromHelpScout($data, $signature) {
    $data = json_encode($data);
    $calculated = base64_encode(hash_hmac('sha1', $data, APP_SECRET_KEY, true));
	
    return $signature == $calculated;
}

$signatureKey = 'X-HelpScout-Signature';
$requestData = $_REQUEST;

if (empty($requestData[$signatureKey])) {
    echo 'Signature query param not provided.';
    return;
}

$signature = $requestData[$signatureKey];
$data = $requestData;
unset($data[$signatureKey]);
// If you have other params in your original callback URL, here is where you would remove them.
// unset($data['my-custom-param']);

if (isFromHelpScout($data, $signature)) {
    echo 'Signature validation passed! 🎉';
} else {
    echo 'Signature validation failed. 😔';
}
?>

The procedure described here ensures you maintain control over the data you receive, adding an additional layer of security and authenticity. Following these steps helps you guard against potential malicious requests or data corruption.

As always, we’re here to help if you have any questions or need further clarification on this process.

↑Back to top
© Help Scout 2024