Webhooks for Surveys

In this article

• About Webhooks for Surveys.
• Setting up Webhooks for Surveys
• Testing webhooks.
• Locating your Webhooks URL.
• When are webhooks triggered?
• Technical documentation for Surveys Webhooks.

Suggested next article: Publishing and Sending Surveys.

About Webhooks for Surveys

The goal of Webhooks for Surveys is to push response data directly to your downstream applications — (e.g. business intelligence tools or products like Zapier that can trigger automations). 

Webhooks provides a convenient way to send customer feedback directly to your team within your organization's existing tech stack. 

Webhooks vs API GET requests

Surveys' Webhooks will send submitted survey responses to the URL of your choice, allowing you to ping other platforms’ APIs and automate your workflows. Webhooks can be advantageous over API GET requests because they trigger in real time — so there’s no need for ongoing API polling.

Back to top

Setting up Webhooks for Surveys

Prior to setting up Delighted Surveys' Webhooks, decide where you want to send the data — whether to an API endpoint from another software application, a link connecting to your data warehouse, or some other URL. (See Locating your Webhooks URL.)

To set up Webhooks for Surveys:

Back to top

Testing webhooks

To test a webhook in Delighted Surveys:

1

From your Webhooks connections page → click Test

Look and see your Webhooks test data

Check out your webhook in the platform you have selected to receive the test. You will see sample test data, and not actual data from your survey.

If you’d like to test the webhook before adding your production URL, we recommend using a site that can collect and inspect incoming HTTP requests like, Webhook.site seen above, or RequestBin. These sites will provide you with a temporary URL that you can send webhooks to, allowing you to review all of the request details from your test. If there's a hiccup, be sure you've properly set up the conditions and added the destination URL. (Review Locating your Webhooks URL.)

Back to top

Locating your Webhooks URL

Most web-based products have a webhooks section that provides a URL that can be used to catch webhook payloads from third-party services, like Delighted Surveys. Typically, these are super easy to find. 

A good example is Zapier. Let’s say you want to set up a Zap to send you a text message every time a new response is received. In Zapier, 1) Catch the webhook and 2) Configure the other action steps needed to automate the sending of an SMS, email, or other type of message to your team.

When you go into Zapier to set-up that first step (catching the webhook), Zapier will display your webhooks URL. Click Copy, and then paste that URL into Surveys Webhooks, as seen in Setting up Webhooks for Surveys step 6.

Back to top

When are webhooks triggered?

A response webhook is triggered by Surveys when a response is: 

Webhooks are triggered 10 minutes after a response is received. This time buffer allows for much of the survey to be completed before we send the webhook payload.

All updates are also delayed by 10 minutes (eg. if someone updates their response after the initial submission, we'll wait 10 minutes before sending a new webhook).

Back to top

Technical documentation for Surveys webhooks

1. Webhook structure

Webhooks are always sent as an HTTP POST request to the webhook URLs you’ve configured via your Webhooks integration. The details of the activity that triggered the webhook are sent as the body of the HTTP request in JSON format. Every webhook will include an event_type property that describes what kind of activity triggered the event.

2. Event types

We currently support sending webhook notifications for the following event types:

3. Example request body for a survey_response object

{
  "event_type": "survey_response.updated",
  "event_id": "ab85fd23a00e4e210f021800107ab77d6e358f32616b066b1f7ce4b10c0d7b20",
  "event_data": {
    "id": "6456",
    "created_at": "2023-08-14T22:50:07Z",
    "updated_at": "2023-08-14T22:50:24Z",
    "survey": {
      "id": "50",
      "name": "New survey 2023-08-14",
      "questions": [
        {
          "id": "72",
          "type": "free_text",
          "text": "How can we improve your experience?"
        },
        {
          "id": "73",
          "type": "numeric_scale",
          "text": "How satisfied are you with the time it took to resolve your issue?",
          "scale_from": 1,
          "scale_to": 10
        },
        {
          "id": "74",
          "type": "graphic_scale",
          "text": "How helpful was your agent?",
          "graphic_type": "stars-5"
        },
        {
          "id": "75",
          "type": "multiple_choice",
          "text": "How did you hear about us?",
          "options": [
            {
              "id": "116",
              "text": "Search engine"
            },
            {
              "id": "117",
              "text": "Instagram"
            },
            {
              "id": "118",
              "text": "YouTube"
            },
            {
              "id": "119",
              "text": "Phone"
            },
            {
              "id": "120",
              "text": "Email"
            },
            {
              "id": "121",
              "text": "Text message"
            },
            {
              "id": "122",
              "text": "Word of mouth"
            },
            {
              "id": "123",
              "text": "TV or radio"
            },
            {
              "id": "124",
              "text": "Our website"
            },
            {
              "id": "125",
              "text": "Third party review"
            },
            {
              "id": "126",
              "text": "Print ad"
            }
          ]
        },
        {
          "id": "76",
          "type": "graphic_scale",
          "text": "How helpful was your agent?",
          "graphic_type": "thumbs"
        }
      ]
    },
    "contact": {
      "id": "6420",
      "email": "test@example.com"
    },
    "answers": [
      {
        "id": "16541",
        "question_id": "72",
        "value": {
          "free_text": "Here's what a text response to your question might look like."
        }
      },
      {
        "id": "16542",
        "question_id": "73",
        "value": {
          "numeric_scale": 6
        }
      },
      {
        "id": "16543",
        "question_id": "74",
        "value": {
          "graphic_scale": 4
        }
      },
      {
        "id": "16544",
        "question_id": "75",
        "value": {
          "multiple_choice": [
            {
              "option_id": "117",
              "text": "Instagram"
            },
            {
              "option_id": "120",
              "text": "Email"
            },
            {
              "option_id": "123",
              "text": "TV or radio"
            },
            {
              "option_id": "126",
              "text": "Print ad"
            }
          ]
        }
      },
      {
        "id": "16545",
        "question_id": "76",
        "value": {
          "graphic_scale": "Thumbs up"
        }
      }
    ]
  }
}

4. Webhook request body parameters

5. Example request headers

6. Responding to webhooks

You should respond with an HTTP status code in the 200 range to indicate that you successfully received the webhook. Any response with a status code outside the 200-299 range, including a redirect, will be treated as a failure, and we will try to deliver the webhook again multiple times over several days.

7. Signature verification

Every webhook includes a unique X-Delighted-Webhook-Signature header that must be used to verify that the request was indeed sent by us. The value of this header comprises two parts: the signature algorithm and the signature itself, divided by an equals sign.

To validate the signature, you must collect the exact HTTP request body as originally transmitted (before decoding the JSON), use your unique webhook signature key, and generate an HMAC digest over the request body, using the signature algorithm specified in the header.

Here’s an example in Ruby:

def webhook_signature_valid?(request)
  unique_webhook_signature_key = ENV['WEBHOOK_SIGNATURE_KEY']
  signature_header = request.headers['X-Delighted-Webhook-Signature']
  algorithm, received_signature = signature_header.split('=', 2)
  if algorithm != 'sha256'
    raise Exception, "Invalid algorithm"
  end
  expected_signature = OpenSSL::HMAC.hexdigest(
    OpenSSL::Digest.new(algorithm), unique_webhook_signature_key, request.body.read
  )
  return SecurityUtils.secure_compare(received_signature, expected_signature)
end

8. Data security

We recommend that your webhooks use HTTPS URLs so that the customer information delivered to you via webhooks is encrypted while traveling over the internet.

Back to top