Webhooks

A way for SaaS applications to send automated messages or information to other applications/systems, Webhooks are a powerful feature that allow you to receive real-time "push-notification" style messages to your web services.

๐Ÿ’ก This article covers

What are Webhooks?

๐Ÿ’ช When to use it

  • If you donโ€™t see your external CRM, database, or application listed in our Integration Manager, simply use Webhooks to integrate data when a survey question or an entire survey is completed.
  • Webhooks are Similar to APIs but are generally simpler. Whereas an API would give access to any of the system functionalities available, which may not be required, Webhooks focus on sending you only the information that your application asked for.

๐Ÿ’ผ What it does

  • Webhooks are delivered to unique URLs, which are made available by your system, and are configured inside of Segmanta. When something changes in your survey with a webhook notification configured, Segmanta sends a JSON (Javascript Object Notation)/POST request to the Webhook's configured URL. 

Note: Segmanta only supports JSON payloads.

Setting up your Webhook

๐Ÿ”จ How it works 

  1. Go to the Survey Editor and click on Configure.
  2. Navigate to the Webhooks tab and click on + Add Hook.
  3. Define the Parameters

In order to activate a Webook, you will need to configure the survey Webhooks to send all answers as they are given (upon question answered). Define those configuration items, including:

  • Name
    Create a name for your Webhook.
  • URL (where to send the data)
    Copy and paste a URL link into the text field where you would like the survey data to be sent to.
  • Event (when to send the data)
    Select if you would like to send the data on survey completion or on question completion. If you select question completion as the Webhook event you will need to define upon completion of which question you would like the Webhook to activate (or upon completion of all questions).
  • Active
    Decide if you would like to activate the Webhook. 

Segmanta sends each answer to your Webhook endpoint with the answer data that has changed/been given, with supporting metadata to allow you to correlate this Webhook request.

Your system then processes the Webhook, saves the data that it requires, and then responds with either a successful HTTP response code (200) or in the case of an error and you'd like to retry later, an error HTTP response code (4xx/5xx).

Pro-tip:

Here's an example of a Webhook in action.

Survey: Customer Satisfaction Survey

System: CRM

Required behavior: For each completed answer to the customer satisfaction survey, attach responses to the customer's CRM record.

Understanding your Webhook's delivery structure

The complete survey response data is sent including question text, selected answer choice, URL parameters, and any labels that have been applied to question pages, questions, and answer choices. 

Response Body

Here is an example of the survey's JSON response body.

{
    "custom_params": {
      "first_name": "first_name value",
      "seg_erid": "seg_erid value"
    },
  "respondent_session_id": #######,
    "results": [
        {
            "has_variants": false,
          "id": #####,
          "name": "Question Text",
            "questions": [
                {
                    "answers": [
                        {
                            "comment": null,
                          "created": "YYYY-MM-DDT00:00:00.000000+00:00",
                            "item": {
                              "id": ######,
                              "name": "Answer Choice",
                              "tag": null
                            }
                        }
                    ],
                  "id": #####,
                  "tag": null,
                  "text": "Question Text"
                }
            ],
          "tag": null,
            "type": "ChoicesQuestionPage"
      }
    ],
  "survey_id": ####,
  "survey_name": "Survey Name",
  "survey_public_id": "Survey Public ID"
}

Note

  • As seen above, "tag" is listed as null. If you have added a label to any of the survey elements, null will be replaced with the label's text.
  • If "has_variants" is listed as "true", the following value of variants will be included at the end of the relevant question page delivery after the question type.
"variant_id": #####,       
"variant_name": "Variant Name"
  • Welcome Page checkbox values are not sent with Webhook deliveries.

Testing your Webhook via RequestBin

After you have set up and activated your Webhook, you can test it by performing the event you have defined in the Webhook's configuration. Once you have performed the event action, you can check the activations on the Webhooks tab.

Pro-tip: Click on the number of activations in order to view more information about each activation including the Webhook data delivered and whether the action succeeded or failed.

The easiest way to get started is to use a public RequestBin (or similar service that accepts HTTP requests in, on SSL, for POST requests) which will receive your test Webhooks whilst you are exploring whether Webhooks is right for you. 

Note: RequestBin provides a service that creates a temporary webhook URL and sends data to it to see how it is structured. However, RequestBin is a public service owned and operated by Pipedream, therefore, we cannot provide support for their services to test Webhooks.

๐Ÿ”จ How it works

  1. Create an account at https://requestbin.com/
  2. Click "Create a RequestBin". It will then display you a Webhook URL which you should copy.
  3. Go to the survey that you would like the Webhooks to be sent from on the Segmanta platform, and navigate to Configure > Webhooks.
  4. Click "Add Hook"
  5. Name your Webhook with something memorable which will help you distinguish configurations.
  6. Paste the URL copied from step 2 into the "Where to send the data field"?
  7. Select from the options, "On Survey Completion" or "On Question Completion"
  8. Set the webhook to "Active"
  9. Open your Production Survey URL (survey previews do not trigger webhooks as data is not persisted for survey sessions), and if your answer to step 7 was "On Survey Completion", complete the survey, or if "On Question Completion", answer a question.
  10. Open the RequestBin page again, and check the data sent by Segmanta for those survey responses through Webhook.

Note: Webhook delivery is usually instant, but may take up to 5 seconds to be delivered. In the case your system is unable to handle a Webhook at this time, Segmanta will retry periodically to try and deliver your system the data.