Using Checkbox Webhooks with Your API

Overview of Checkbox Webhooks

Checkbox webhooks can be added to any page of your survey, allowing you to post real-time response data to an API of your choice. One of the most common tools to integrate with webhooks is Zapier, but you can also create your own API to submit the webhook to which this guide will help with. 

 

Pre-requisites: 

  • Some coding knowledge 
  • An API that you host to submit the webhook to

If you do want to use webhooks, but don't want to write code or have your own API we suggest you look at our Zapier webhook guide here: https://help.checkbox.com/hc/en-us/articles/360051014532-Using-Checkbox-Webhooks-with-Zapier

 

1. Create an endpoint on your API to submit the Webhook to

In order to post the webhook data Checkbox will need an endpoint that it can send the data to. For this you will want to create an endpoint in your API or website that you can submit data to. For testing we recommend you utilize this tool here: https://webhook.site which can be utilized to test your endpoints and see the data structure you should expect. This is a third party site, so make sure that you do not submit sensitive data to your survey while using this as a webhook. 

 

2. Enable the Webhook Item in Checkbox

For security reasons, the webhook item is disabled by default in Checkbox. System administrators can enable the item by going to the Application Settings -> Survey -> Advanced Settings -> Enable webhook item. This step only needs to be performed once, prior to creating your first webhook.

 

3. Add a Webhook Item to your Survey

Although you can add a webhook item to any page of your survey, it is most commonly added to the Completion Page. Adding the webhook to the Completion Page will result in Checkbox sending the entire response to your API when the respondent submits their response. 

  • Edit your survey
  • Expand the “Completion Page”
  • Click “Add Action Item” and choose the Webhook item
  • In the Webhook URL field, paste the API endpoint that you created from Step 1. 

Screen_Shot_2020-10-23_at_3.19.07_PM.png

 

4. Test your Webhook

Create a test survey response in Checkbox to test your webhook. This should submit the data to your API. This is where the tool https://webhook.site can be helpful. Testing at this stage will make the following steps easier to complete and test. 

 

5.  Pares the response data

Below is the webhook data for a simple survey with a single radio button question "Red or Blue". Your response data will be different depending on your survey questions and the number of pages you have but the basic structure should be similar.  

 

You can parse the data pretty easily like this example which pulls the question id, text, and answer for any questions that have options: 

response.response.pages.forEach(page => {
page.items.forEach(item=> {
if(item.answer != null){
console.log(`${item.item_id}${item.question_text}${item.answer.choice_text}`)
}});
});

 

You can then parse this data and then store it in a database or trigger automatic internal alerts on your end, or just send the data off to a third party like Salesforce. 

{
  "id": "730ebe33-d5fa-4b03-bee4-5b8ea2d10d93",
  "timestamp": "2021-02-04T16:24:49.7435889+00:00",
  "response": {
    "pages": [
      {
        "title": "Hidden Items",
        "items": [],
        "page_id": 1102,
        "page_type": "HiddenItems",
        "started": "2021-02-04T11:24:47.823-05:00",
        "ended": "2021-02-04T11:24:47.823-05:00",
        "excluded": false,
        "pipe_values": [],
        "page_score": 0,
        "first_question_number": null
      },
      {
        "title": "",
        "items": [
          {
            "item_id": 1597,
            "item_type": "RadioButtons",
            "excluded": false,
            "position": 1,
            "question_text": "<p>Red or Blue</p>",
            "data": {
              "choices": [
                4240,
                4241
              ],
              "data_type": "Choices"
            },
            "answer": {
              "choice_id": 4241,
              "choice_text": "Blue",
              "answer_type": "SingleChoice"
            }
          }
        ],
        "page_id": 1103,
        "page_type": "ContentPage",
        "started": "2021-02-04T11:24:47.823-05:00",
        "ended": "2021-02-04T11:24:49.7435889-05:00",
        "excluded": false,
        "pipe_values": [],
        "page_score": 0,
        "first_question_number": 1
      },
      {
        "title": "Completion Events",
        "items": [
          {
            "item_id": 1596,
            "item_type": "Message",
            "excluded": false,
            "position": 1
          },
          {
            "item_id": 1598,
            "item_type": "Webhook",
            "excluded": false,
            "position": 2
          }
        ],
        "page_id": 1104,
        "page_type": "Completion",
        "started": "2021-02-04T11:24:49.7435889-05:00",
        "ended": "2021-02-04T11:24:49.7435889-05:00",
        "excluded": false,
        "pipe_values": [],
        "page_score": 0,
        "first_question_number": null
      }
    ],
    "current_page_id": 1104,
    "page_path": [
      1103,
      1104
    ],
    "total_time_in_seconds": 1,
    "score": 0,
    "progress": {
      "current_page_number": 1,
      "total_page_count": 1
    },
    "id": "CFFF43CE-107A-4A8C-8944-2E85B0E1F11B",
    "numeric_id": 1163,
    "survey_id": 1024,
    "status": "Completed",
    "language": "en-US",
    "started": "2021-02-04T11:24:47.823-05:00",
    "last_edit": "2021-02-04T11:24:49.7435889-05:00",
    "ended": "2021-02-04T11:24:49.7435889-05:00",
    "ip_address": "127.0.0.1",
    "is_test": true,
    "contact_id": null,
    "anonymous_respondent_id": "B4F5BC90-B439-48BD-A97F-DDE65124DC8D",
    "invitee": null,
    "is_anonymized": false,
    "import_batch_id": null
  }
}



0 Comments

Article is closed for comments.