Introduction

The SmartSurvey Webhook API enables you to subscribe and unsubscribe to receive notifications about certain events when they occur in SmartSurvey.

On subscribing for the Webhook API, you will receive a notification from SmartSurvey after the event occurs via a POST request. The POST request will contain information related to the event which has occurred. This POST request will be made to the "endpoint_url" which you will have to specify at the time of subscribing for the Webhook API.

Configure Webhook URLs

Add a new webhook in your SmartSurvey account

To add a new webhook using the SmartSurvey web application:

• Navigate to My Account in your SmartSurvey account.
• Click Webhooks from the left menu.
• Click + Add a Webhook at the top of the page.
• Choose the events you want to listen for (for example, when a survey response is completed, disqualified or updated.).
• Add your webhook URL under Post To URL.
• Give your webhook an optional description under Description.
• Click Create Webhook.

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 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 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. 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!')
}