Signed Webhooks

Webhooks are by default sent by our servers over HTTPS. If you want additional security and be able to verify that webhooks indeed are sent by us, you can verify this by checking the signature of the request.

How it works

The JSON/XML payload of webhook is the same as it is now, unencrypted and unhashed, no difference.

The request will contain a header, X-SmartSurvey-Signature, that contains a string with a HMAC sha256 hash of the JSON/XML payload (stringified) and our shared secret. All requests will contain this header, you do not need to activate anything additional in SmartSurvey to use this feature of webhooks.

The value of the secret can be seen in the webhook settings screen of your account, or for a survey webhook, underneath the Automate -> Webhooks section. Each Webhook will have its own secret key, listed as "Signature Key", as in the example below:

With node.js, you would verify the signature something like this:

const crypto = require('crypto');

const secret = 'our-shared-signature-key';
const payload = 'the JSON payload from our request'
const header = 'the x-smartsurvey-signature value from our request'

const hash = crypto
  .createHmac('sha256', secret)
  .update(payload)
  .digest('hex');

if (hash === header) {
  console.log('boom, request is verified!')
}