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, we can sign the webhooks with a secret.

How it works

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

The only difference is that we'll add a header to the request, X-SmartSurvey-Signature, that contains a string with a HMAC sha256 hash of the JSON payload (stringified) and our shared secret.

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