Webhooks allow you to send responses to surveys to a URL of your choosing, making it easy to integrate survey results back into your internal database. A webhook is sent each time someone completes your survey (one request for each person who completes it).

First you will need to create an Iterate account, and make a survey.

1. Add a webhook

Once you create a survey you'll see a "Webhooks" link on the "View Feedback" tab of your survey

Click on that link and you'll be taken to the webhooks page where you can add a webhook by entering the URL you'd like to receive requests at.

2. Test

Once you've added a webhook you can click the "test" link to send a sample webhook request to the URL. The data sent will be just a sample, but represent the same format that the real data will be sent in.

3. Receive the webhook request

Webhooks are sent with an HTTP POST request, and the request body is in JSON format. A webhook represents a single person filling out a single survey. You should respond to the request with a 2XX letting us know the request succeeded, if there was an error delivering the webhook we will not attempt to resend it.

Typically you'll want to use the data in the user object to identify the user and tie them to your internal user, then save each response's "question_prompt" and "formatted_response"

The attribute "survey_response" at the top level of the request body contains the following a child attributes. See a sample request to see all attributes.

survey
This object contains information about the survey itself including the list of all questions

id - string - id of the survey
questions - array - list of questions in the survey

responses
This array contains the responses from the user for the survey

created_at - string - timestamp when the response was created
formatted_response - string - a formatted response, suitable for saving in your database
id - string - id of the response
question_id - string - id of the question
question_prompt - string - the question prompt
question_type - string - the question type
response - varies - the raw response value
user_id - string - user id

user

email - string - email address of the user if we have one
id - string - user id
first_name - string - first name of the user if we have one
last_name - string - last name of the user if we have one
traits - object - custom user traits associated with the user

Determining when a survey is completed

We determine that a user is finished filling out your survey when they stop answering questions for at least 10 minutes. Since users fill out your surveys one question at a time, for users who don't get to the end of the survey we are unable to know exactly when they're "done" filling out your survey so we use 10 minutes as the cut off.

Note that this means all webhooks will be delayed by roughly 10 minutes from when the last question was answered by that user. If you need the exact time you can reference the "completed_at" attribute of the survey response.

Identifying Users

Webhooks are a powerful way to enrich the data of your users in your own database. In order to do that you'll need to use an attribute to identify the user. If you're sending an email survey, the email address works great. If you're running surveys on your website, use the Identify command of our JS SDK to associate any user data you'll need.

Notes

  • Your webhook URL can be either http or https and can include port numbers
  • You can have up to 5 webhooks per survey, let us know if you need more
  • We do not retry to send webhooks for failed requests
Did this answer your question?