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?
• Setting up your Webhook
• Understanding your Webhook's delivery structure
• Testing your Webhook via RequestBin

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. 

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). You may also define upon completion of which ending or all endings.

• HTTP Header
  This is an optional field. HTTP header consists of key-value pair that can be passed as part of the headers which can be used for authorization or other additional information.
• 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).

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 upon survey completion.

{
    "custom_params": {
        "first_name": "first_name value",
        "seg_erid": "seg_erid value"
    },
    "ending": {
        "id": ######,
        "name": "Ending Name",
        "tag": null
    },
    "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"
}

"variant_id": #####,       
"variant_name": "Variant Name" 

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.

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. 

🔨 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.