Securing your webhooks

Introduction

In this document, we will guide you through the steps required to generate, set up, and verify a webhook secret token as an additional security measure. This way, you will be able to verify whether or not incoming webhooks are coming from Autify.

Webhook secrets

A webhook secret token is a string used for verifying the authenticity of the payload you will receive at your endpoint. This value must be generated by you, and then set in Autify also by you.

Risks of not using Webhook secrets

If you don't use a webhook secret, you run the following risks:

• Unable to validate whether requests are coming from us, or not

• Unable to validate whether the payload has been tampered, or not

Changes when you set up Webhook secrets

When you set up a webhook secret token, Autify will use it to create a hash signature for each payload. This signature is encoded as a header in the request asX-Autify-Signature. We are using Hash-based Message Authentication Code (HMAC) to calculate the signature for each payload.

# Example of request from Autify
POST /payload HTTP/1.1 
Host: localhost:4567 
X-Autify-Signature: sha1=7d38cdd689735b008b3c702edd92eea23791c5f6 
Content-Type: application/json 

 <Payload>

Creating and define Webhook secrets

1. Navigate to the setting page of the workspace where you want to set up a webhook

2. Generate a string. Use values that are hard to guess, such as randomly generated.

# Example of generating random values
＄ openssl rand -hex 20b2f82af62f9980f6b01e1cd7e716230d0a063f58

3. Key in the secret token field with the generated value

4. Click Create or Update button

Validating the payload with webhook secrets

The payload is verified in the following ways:

1. Calculate HMAC for a payload using the webhook secret

2. Concatenate the value obtained in (1) at the end of sha1=

3. Retrieves the value of the received request headerX-Autify-Signature

4. Compare the values obtained in (2) and (3) and verify that they match.

   • Note: If the values do not match, the request may come from a source other than Autify.

Here's an example of how to verify the value in each language:

Ruby

$ gem install rack

require 'openssl'
require 'rack'

digest = OpenSSL::HMAC.hexdigest(
  OpenSSL::Digest.new('sha1'),
  '<Webhook secret>',
  '<payload>'
)

computed_signature = "sha1=${digest}"
request_signature  = '<X-Autify-Signature>'

Rack::Utils.secure_compare(
  computed_signature, 
  request_signature
)

Node.js

$ npm install crypto

const crypto = require('crypto');

const digest = crypto
  .createHmac('sha1','<Webhook secret>')
  .update('<payload>')
  .digest('hex')

const computedSignature = `sha1=${digest}`
const requestSignature  = '<X-Autify-Signature>'

crypto.timingSafeEqual(
  Buffer.from(computedSignature, 'utf8'), 
  Buffer.from(requestSignature, 'utf8')
)