HMAC for Webhooks

If you’d like to add an extra step to your security measures, you may use HMAC to check if your webhooks were tampered with in transit. Acquire's HMAC for Webhooks uses the industry standard SHA-256 hash function to match signatures between sender and receiver. 

Keep in mind that HMAC is not an end to end security measure. It should be used in addition to your other security methods.

At this time, HMAC for webhooks ONLY works for outbound webhooks. 

In this article: 

• Step 1: Adding the validateSignature function to Your Codebase 
• Step 2: Adding the HMAC Key to a Webhook

You will need:

• Access to your site's codebase 
• Knowledge of webhooks and Javascript

Step 1: Adding the validateSignature function to Your Codebase 

To implement this function, you will need access to your code base. 

The following function is written in Node.js. You may need to require the crypto library, e.g., const crypto = require(‘crypto’) to use it in your codebase.

validateSignature = (secret, body, signature) => {

// Create a SHA256 hashed code using the HMAC/Secret key and update the hash with body using utf8

var signatureComputed = crypto.createHmac('SHA256', secret).update(

new Buffer(JSON.stringify(body), 'utf8')).digest('hex');

return (signatureComputed === signature);

};

The arguments to this function should include the following variables: 

• The secret refers to a string you’ve generated yourself. 
• The body variable refers to the webhook payload. 
• The signature will be the HMAC output value. 

This function outputs a true or false boolean. 

In addition, you should write additional code to handle the output of the validateSignature function. For example, if the function returns false, you may want to try to verify a second time, and stop the verification process if it continues to fail. If the function returns true, then it is likely that the message was not tampered with in transit. 

Step 2: Adding the HMAC Key to a Webhook

Once you’ve set up the function(s) on your backend application, you may set up the webhook in Acquire. Navigate to Settings > For Developers > Webhooks and click on ‘Create Webhook’.
How to set up:

• In the setup menu, write the webhook’s name. 
• Set the Webhook Flow to ‘Outbound’ and set its status to ‘Active’.
• Choose ‘json’ as the format encoding and then notification email you’d like to send failure notices to (should your webhook fail). 
• The 'secret' is a user-generated string. This ‘Secret key’ should be the same ‘secret’ used in the validateSignature argument. Ensure that this secret is not exposed (for example, via a screenshot). 
• Enable or disable the option to 'skip SSL verification'. 
• Select the events you’d like to trigger your webhook. 
• Then, press ‘Save’.

Once you receive the outbound webhook:

• In the headers section of the response, there will be a key x-acquire-signature. The value of the key will be used to verify that the message received was not tampered with in transit. 
• The response should look something like this: 

^{

^{"headers": {}

^{"host": "your-webhook-host",}

^{"content-length": "285",}

^{"content-type": "application/json",}

^{"x-acquire-signature": "your-HMAC-signature-value",}

^{"x-acquire-attempt": "1",}

^}

^[...]

^}

Having trouble? Reach out to support@acquire.io.

References: 

• Acquire Developer Docs Webhook Security
• Okta HMAC Definition