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. We have two options, a webhook that is sent each time someone completes a specific survey (one request for each person who completes it), or when someone responds to any of your company’s surveys.

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 200 letting us know the request succeeded, if there was an error delivering the webhook we will attempt to resend it until we get a successful response 1 hour later, then again 6 hours later and a final attempt 24 hours later.

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"

See the sample request below. There will be additional properties sent with the webhook that you can safely ignore, the documented properties below are the recommended ones to use.

Request

Property

Type

Description

event_type

string

The values will always be "survey_response"

survey_response

Survey Response

The responses of a single user to a single survey

Survey Response

Property

Type

Description

completed_at

string

Timestamp when the survey was completed in ISO 8601 format

survey

Survey

Survey object data

project

Project

Data for the project the survey's in

Survey

Property

Type

Description

id

string

id of the survey

name

string

Name of the survey

questions

array of Question

list of questions in the survey

Question

Property

Type

Description

id

string

id of the survey

question_type

string

Type of question (select, multiselect, etc)

prompt

string

Question prompt

Response

Property

Type

Description

created_at

string

Timestamp when the survey was completed in ISO 8601 format

formatted_response

string

A formatted version of the user's response

id

string

The response id

question_id

string

The question id

question_prompt

string

The question prompt

question_type

string

Type of question (select, multiselect, etc)

user_id

string

The user id

User

Property

Type

Description

id

string

The user id

traits

array of Trait

List of user properties (formerly known as traits)

email

string

If you set the user property 'email', it's treated specially and moved to the top level of the user object

Trait

Property

Type

Description

trait_name

string

Name of the trait

value

string, number, or boolean

Value of the trait, the type is determined by the first value received for that trait.

Project

Property

Type

Description

id

string

The project id

name

string

Name of the project

Example Request


{
"event_type": "survey_response",
"survey_response": {
"completed_at": "2018-02-11T04:25:46Z",
"survey": {
"id": "5a7fc5cab3801f005700003f",
"questions": [{
"id": "5a7fc5cab3801f005700003c",
"question_type": "select",
"prompt": "What's your primary reason for not purchasing?",
}]
},
"responses": [{
"created_at": "2018-02-11T04:25:46.496046162Z",
"formatted_response": "Going to purchase later",
"id": "5a7fc5cab3801f0057000040",
"question_id": "5a7fc5cab3801f005700003c",
"question_prompt": "What's your primary reason for not purchasing?",
"question_type": "select",
"response": {
"value": "going_to_purchase_later"
},
"user_id": "5a7fc5cab3801f005700003a"
}],
"user": {
"email": "[email protected]",
"id": "5a7fc5cab3801f005700003a",
"traits":[{
"trait_name":"breed",
"value":"Australian Shepherd"
},{
"trait_name":"subscribed",
"value":true
}]
}
}
}

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.

Verifying Webhook Requests

See our article with details on how to verify webhook requests.

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 or the Identify command of our mobile SDKs 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 retry sending webhook up to 3 times. 1 hour after the first failure, 6 hours after the second failure, and 24 hours after the third failure.

Did this answer your question?