Webhooks deliver the responses to your typeforms in JSON format. Let's walk through each object in a typical webhook payload. First, here's what a complete payload looks like when it's delivered to a webhook:
{
"event_id": "LtWXD3crgy",
"event_type": "form_response",
"form_response": {
"form_id": "lT4Z3j",
"token": "a3a12ec67a1365927098a606107fac15",
"submitted_at": "2018-01-18T18:17:02Z",
"landed_at": "2018-01-18T18:07:02Z",
"calculated": {
"score": 9
},
"variables": [
{
"key": "score",
"type": "number",
"number": 4
},
{
"key": "name",
"type": "text",
"text": "typeform"
}
],
"hidden": {
"user_id": "abc123456"
},
"definition": {
"id": "lT4Z3j",
"title": "Webhooks example",
"fields": [
{
"id": "DlXFaesGBpoF",
"title": "Thanks, {{answer_60906475}}! What's it like where you live? Tell us in a few sentences.",
"type": "long_text",
"ref": "readable_ref_long_text",
"allow_multiple_selections": false,
"allow_other_choice": false
},
{
"id": "SMEUb7VJz92Q",
"title": "If you're OK with our city management following up if they have further questions, please give us your email address.",
"type": "email",
"ref": "readable_ref_email",
"allow_multiple_selections": false,
"allow_other_choice": false
},
{
"id": "JwWggjAKtOkA",
"title": "What is your first name?",
"type": "short_text",
"ref": "readable_ref_short_text",
"allow_multiple_selections": false,
"allow_other_choice": false
},
{
"id": "KoJxDM3c6x8h",
"title": "When did you move to the place where you live?",
"type": "date",
"ref": "readable_ref_date",
"allow_multiple_selections": false,
"allow_other_choice": false
},
{
"id": "PNe8ZKBK8C2Q",
"title": "Which pictures do you like? You can choose as many as you like.",
"type": "picture_choice",
"ref": "readable_ref_picture_choice",
"allow_multiple_selections": true,
"allow_other_choice": false,
"choices": [
{
"id": "eXnU3oA141Cg",
"ref": "238d1802-9921-4687-a37b-5e50f56ece8e",
"label": "London"
},
{
"id": "aTZmZGYV6liX",
"ref": "d867c542-1e72-4619-908f-aaae38cabb61",
"label": "Sydney"
}
]
},
{
"id": "Q7M2XAwY04dW",
"title": "On a scale of 1 to 5, what rating would you give the weather in Sydney? 1 is poor weather, 5 is excellent weather",
"type": "number",
"ref": "readable_ref_number1",
"allow_multiple_selections": false,
"allow_other_choice": false
},
{
"id": "gFFf3xAkJKsr",
"title": "By submitting this form, you understand and accept that we will share your answers with city management. Your answers will be anonymous will not be shared.",
"type": "legal",
"ref": "readable_ref_legal",
"allow_multiple_selections": false,
"allow_other_choice": false
},
{
"id": "k6TP9oLGgHjl",
"title": "Which of these cities is your favorite?",
"type": "multiple_choice",
"ref": "readable_ref_multiple_choice",
"allow_multiple_selections": false,
"allow_other_choice": false,
"choices": [
{
"id": "4WIlUvKOl0UB",
"ref": "a8fb7094-83b0-470d-be00-7767cd6f8655",
"label": "London"
},
{
"id": "vLZWecsW8HM6",
"ref": "45982537-84ce-4ee3-a619-8ac317c12ee1",
"label": "Sydney"
}
]
},
{
"id": "RUqkXSeXBXSd",
"title": "Do you have a favorite city we haven't listed?",
"type": "yes_no",
"ref": "readable_ref_yes_no",
"allow_multiple_selections": false,
"allow_other_choice": false
},
{
"id": "NRsxU591jIW9",
"title": "How important is the weather to your opinion about a city? 1 is not important, 5 is very important.",
"type": "opinion_scale",
"ref": "readable_ref_opinion_scale",
"allow_multiple_selections": false,
"allow_other_choice": false
},
{
"id": "WOTdC00F8A3h",
"title": "How would you rate the weather where you currently live? 1 is poor weather, 5 is excellent weather.",
"type": "rating",
"ref": "readable_ref_rating",
"allow_multiple_selections": false,
"allow_other_choice": false
},
{
"id": "pn48RmPazVdM",
"title": "On a scale of 1 to 5, what rating would you give the general quality of life in Sydney? 1 is poor, 5 is excellent",
"type": "number",
"ref": "readable_ref_number2",
"allow_multiple_selections": false,
"allow_other_choice": false
},
{
"id": "M5tXK5kG7IeA",
"title": "Book a time with me",
"type": "calendly",
"ref": "readable_ref_calendly",
"properties": {}
}
],
"endings": [
{
"id": "dN5FLyFpCMFo",
"ref": "01GRC8GR2017M6WW347T86VV39",
"title": "Bye!",
"type": "thankyou_screen",
"properties": {
"button_text": "Create a typeform",
"show_button": true,
"share_icons": true,
"button_mode": "default_redirect"
}
}
]
},
"answers": [
{
"type": "text",
"text": "It's cold right now! I live in an older medium-sized city with a university. Geographically, the area is hilly.",
"field": {
"id": "DlXFaesGBpoF",
"type": "long_text"
}
},
{
"type": "email",
"email": "laura@example.com",
"field": {
"id": "SMEUb7VJz92Q",
"type": "email"
}
},
{
"type": "text",
"text": "Laura",
"field": {
"id": "JwWggjAKtOkA",
"type": "short_text"
}
},
{
"type": "date",
"date": "2005-10-15",
"field": {
"id": "KoJxDM3c6x8h",
"type": "date"
}
},
{
"type": "choices",
"choices": {
"ids": ["eXnU3oA141Cg", "aTZmZGYV6liX"],
"labels": ["London", "Sydney"],
"refs": [
"238d1802-9921-4687-a37b-5e50f56ece8e",
"d867c542-1e72-4619-908f-aaae38cabb61"
]
},
"field": {
"id": "PNe8ZKBK8C2Q",
"type": "picture_choice"
}
},
{
"type": "number",
"number": 5,
"field": {
"id": "Q7M2XAwY04dW",
"type": "number"
}
},
{
"type": "boolean",
"boolean": true,
"field": {
"id": "gFFf3xAkJKsr",
"type": "legal"
}
},
{
"type": "choice",
"choice": {
"id": "4WIlUvKOl0UB",
"label": "London",
"ref": "a8fb7094-83b0-470d-be00-7767cd6f8655"
},
"field": {
"id": "k6TP9oLGgHjl",
"type": "multiple_choice"
}
},
{
"type": "boolean",
"boolean": false,
"field": {
"id": "RUqkXSeXBXSd",
"type": "yes_no"
}
},
{
"type": "number",
"number": 2,
"field": {
"id": "NRsxU591jIW9",
"type": "opinion_scale"
}
},
{
"type": "number",
"number": 3,
"field": {
"id": "WOTdC00F8A3h",
"type": "rating"
}
},
{
"type": "number",
"number": 4,
"field": {
"id": "pn48RmPazVdM",
"type": "number"
}
},
{
"type": "url",
"url": "https://calendly.com/scheduled_events/EVENT_TYPE/invitees/INVITEE",
"field": {
"id": "M5tXK5kG7IeA",
"type": "calendly",
"ref": "readable_ref_calendly"
}
}
],
"ending": {
"id": "dN5FLyFpCMFo",
"ref": "01GRC8GR2017M6WW347T86VV39"
}
}
}Now, let's take a closer look at the elements in each part of the response.
{
"event_id": "LtWXD3crgy",
"event_type": "form_response",
"form_response": {
"form_id": "lT4Z3j",
"token": "a3a12ec67a1365927098a606107fac15",
"submitted_at": "2018-01-18T18:17:02Z",
"landed_at": "2018-01-18T18:07:02Z",
"calculated": {
"score": 9
},
"variables": [
{
"key": "score",
"type": "number",
"number": 4
},
{
"key": "name",
"type": "text",
"text": "typeform"
}
],
"hidden":{
"user_id": "abc123456"
},| Element | Type | Description | ||
|---|---|---|---|---|
| event_id | string | Unique ID for the webhook. Automatically assigned by Typeform. | ||
| event_type | string | Reason the webhook is being sent. | ||
| form_response | object | Object that contains information about the typeform and account associated with the webhook. | ||
| form_id | string | Unique ID for the typeform. Find in your form URL. For example, in the URL https://mysite.typeform.com/to/u6nXL7, the form_id is u6nXL7. | ||
| token | string | Unique ID for the typeform submission. This is identical to response id in the Responses API. | ||
| submitted_at | string | Date and time the typeform responses were submitted. In ISO 8601 format, Coordinated Universal Time (UTC), to the second. "T" is a delimiter between the date and time. For example, July 26, 2017 at 11:10 p.m. and 20 seconds is expressed as 2017-07-26T23:30:20. | ||
| landed_at | string | Date and time of the form landing. In ISO 8601 format, Coordinated Universal Time (UTC), to the second. "T" is a delimiter between the date and time. For example, July 26, 2017 at 11:10 p.m. and 20 seconds is expressed as 2017-07-26T23:30:20. | ||
| calculated | object | If your typeform includes a score calculation, the webhook response will contain this object. | ||
| score | integer | Score the respondent entered. | ||
| variables | array | If your typeform has variables, this array contains all the variables of the typeform and their values. | ||
| key | string | Unique identifier for the variable. | ||
| type | string | Type of the variable, could either be text or number. | ||
| number | integer | If the variable is of type number, contains the numerical value of the variable. | ||
| text | string | If the variable is of type text, contains the text value of the variable. | ||
| hidden | object | If your typeform has hidden fields, the webhook response will contain an object with the value of each hidden field. |
"definition": {
"id": "lT4Z3j",
"title": "Webhooks example",
"fields": [definition is an object that lists the questions in your typeform. You can use the definition to match questions with answers and ending reference with ending screens.
| Element | Type | Description |
|---|---|---|
| id | string | Unique ID for the typeform. Find in your form URL. For example, in the URL https://mysite.typeform.com/to/u6nXL7, the form_id is u6nXL7. |
| title | string | Title of the typeform. |
| fields | array | Questions in your typeform. Order of the fields in this questions array matches the order of fields in the answers array (which is included later in the payload). |
Each object in the fields array may include six elements:
| Element | Type | Description |
|---|---|---|
| id | string | Unique ID for the field. You can use the field id to match questions with answers. |
| title | string | Title of the question associated with the field. |
| type | string | Question type. |
| ref | string | A name you can use to reference the field. When you create a form with the Create API, you can specify a readable ref for each field. If you don't specify a ref or you create your form through the Typeform admin panel, our system will generate a non-persistent ref for each field. The system-generated ref will look something like 0e1178a0-67f0-4779-90f1-78e7420f49c9 and will be different in every payload. It must be less than 255 characters and in valid regular expression format ^[a-zA-Z0-9_-]+$. |
| allow_multiple_selections | Boolean | true if respondents can select more than one answer choice. false if respondents can select only one answer choice or the question is not a multiple_choice or picture_choice question type. |
| allow_other_choice | Boolean | true if the question includes an "Other" option so respondents can enter a different answer choice from those listed. false if the question limits answer choices to those listed or the question is not a multiple_choice or picture_choice question type. |
| choices | array | if multiple_choice, picture_choice, dropdown question type, contains a list of choices for this field. |
| id | string - Unique ID for the choice. | |
| label | string - Label for the choice. | |
| ref | string - Auto-generated identifier for the choice that can be changed programatically. |
answers is an array of objects that lists the answers for the questions in your typeform.
Each object in the answers array generally includes five elements:
| Element | Type | Description | |
|---|---|---|---|
| type | string | Type of the answer: text for short_text and long_text; choice for dropdown, multiple_choice, and picture_choice; choices for dropdown, multiple_choice, and picture_choice when the "multiple selections" option is activated; date for date; boolean for legal and yes_no; number for rating, opinion_scale, and number; file_url for file_upload; payment for payment; and calendly for calendly. | |
| {answer} | string, object, integer, Boolean | Respondent's answer to the question. Depends on the answer type: for example, text means the answer is a string; choice means the answer is an object that lists the label for the respondent's choice as a string. url means the answer is a url. | |
| field | object | Object that contains identifying information to help you match the answer with the question. | |
| id | string | Unique ID for the field. You can use the field id to match questions with answers. | |
| type | string | Type of question associated with the field. Values are described in the Field types section below. | |
| ref | string | A name you can use to reference the field. |
Your webhooks payload may include these field types in the answers array, depending on the questions in your typeform.
short_text and long_text){
"type": "text",
"text": "Lorem ipsum dolor",
"field": {
"id": "JwWggjAKtOkA",
"type": "short_text",
"ref":"readable_ref_shorttext"
}
},
{
"type": "text",
"text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
"field": {
"id": "DlXFaesGBpoF",
"type": "long_text",
"ref":"readable_ref_longtext"
}
},dropdown, multiple_choice, picture_choice and rankingFor single-selection choice fields, the choice object contains either the selected choice properties (id, label and ref) or other. If the "Other" option is disabled (your typeform does not allow respondents to enter their own answers), choice will contain id, label and ref.
For multiple-selection choice fields, if respondents use the "Other" option to enter their own answers, the choices object will contain both ids, labels, refs of the selected choices and other. If respondents do not use the "Other" option or the "other" option is disabled (your typeform does not allow respondents to enter their own answers), choices will contain ids, labels and refs.
{
"type": "choice",
"choice": {
"id": "meFVw3iGRxZB",
"label": "Lorem Ipsum",
"ref": "ed7f4756-c28f-4374-bb65-bfe5e3235c0c"
},
"field": {
"id": "LXe7ZKAK2C2R",
"type": "dropdown",
"ref":"readable_ref_dropdown"
}
},
{
"type": "choices",
"choices": {
"ids": [
"eXnU3oA141Cg",
"aTZmZGYV6liX"
],
"labels": [
"London",
"Sydney"
],
"refs": [
"238d1802-9921-4687-a37b-5e50f56ece8e",
"d867c542-1e72-4619-908f-aaae38cabb61"
],
"other": "Other text"
},
"field": {
"id": "k6TP9oLGgHjl",
"type": "multiple_choice",
"ref":"readable_ref_multiplechoice"
}
},
{
"type": "choice",
"choice": {
"id": "4WIlUvKOl0UB",
"label": "London",
"ref": "a8fb7094-83b0-470d-be00-7767cd6f8655"
},
"field": {
"id": "PNe8ZKBK8C2Q",
"type": "picture_choice",
"ref":"readable_ref_picturechoice"
}
},email){
"type": "email",
"email": "name@example.com",
"field": {
"id": "SMEUb7VJz92Q",
"type": "email",
"ref":"readable_ref_email"
}
},date)Dates are always returned in YYYY-MM-DD format, no matter which input format you configured on the front-end for your typeform’s date field. You might need to make time zone adjustments in your code.
{
"type": "date",
"date": "2005-10-15",
"field": {
"id": "KoJxDM3c6x8h",
"type": "date",
"ref":"readable_ref_date"
}
},legal and yes_no){
"type": "boolean",
"boolean": true,
"field": {
"id": "gFFf3xAkJKsr",
"type": "legal",
"ref":"readable_ref_legal"
}
},
{
"type": "boolean",
"boolean": false,
"field": {
"id": "RUqkXSeXBXSd",
"type": "yes_no",
"ref":"readable_ref_yesno"
}
},website and calendly){
"type": "url",
"url": "https://typeform.com",
"field": {
"id": "r5TP2oPGgHpc",
"type": "website",
"ref":"readable_ref_website"
}
},
{
"type":"url",
"url":"https://calendly.com/scheduled_events/EVENT_TYPE/invitees/INVITEE",
"field": {
"id":"KllelCwSWtVq",
"type":"calendly",
"ref":"readable_ref_calendly"
}
}rating, opinion_scale, and number){
"type": "number",
"number": 3,
"field": {
"id": "WOTdC00F8A3h",
"type": "rating",
"ref":"readable_ref_rating"
}
},
{
"type": "number",
"number": 2,
"field": {
"id": "NRsxU591jIW9",
"type": "opinion_scale",
"ref":"readable_ref_opinion_scale"
}
},
{
"type": "number",
"number": 5,
"field": {
"id": "Q7M2XAwY04dW",
"type": "number",
"ref":"readable_ref_number"
}
},file_upload){
"type": "file_url",
"file_url": "https://d31kvrskfu54aq.cloudfront.net/web/uploads/2014/08/11094555/share_typeform.jpg",
"field": {
"id": "F9M3CArY00dS",
"type": "file_upload",
"ref": "readable_ref_fileupload"
}
}payment)If your typeform collects a credit card payment, the webhook response will include a payment object with four elements:
| Element | Type | Description |
|---|---|---|
| amount | string | Amount of the payment. In the currency you selected when you built your typeform. |
| last4 | string | Last four digits of the credit card used to make the payment. |
| name | string | Name on the credit card used to make the payment. |
| success | Boolean | true if the payment was processed successfully. Otherwise, false. |
{
"type": "payment",
"payment": {
"amount": "1",
"last4": "1234",
"name": "John Doe",
"success": true
},
"field": {
"id": "T6E2XAwU83AS",
"type": "payment"
}
}multi_format)When collecting answers via a Video question, the webhook payload will include a multi_format object
containing the answer.
When a respondent chooses to write text instead of recording a video the webhook will receive:
{
"type": "multi_format",
"multi_format": {},
"field": {
"id": "40BMO0jworna",
"type": "multi_format",
"ref": "0341a2ee-43b2-4954-972e-dbce42d03101"
}
}When the respondent records a video, then video_id and transcript fields are part of the payload:
{
"type": "multi_format",
"multi_format": {
"video_id": "349cd5c3-366f-4c0c-b13c-49c9e73d035d",
"transcript": "That's a transcript of what the respondent said"
},
"field": {
"id": "wwVznbEmbUUq",
"type": "multi_format",
"ref": "0341a2ee-43b2-4954-972e-dbce42d03101"
}
}The answers array is populated only with answered questions. If a question isn't answered because it’s not required or it's skipped by a Logic Jump, it won’t be in the webhook payload.
Typeforms finish with an Ending Screen, which appears after respondents click submit. A typeform can have multiple endings according to the form's logic. The webhook displays information under the field ending which contains the ID and the reference.
You can match the entire ending using form definition.
"ending": {
"id": "dN5FLyFpCMFo",
"ref": "01GRC8GR2017M6WW347T86VV39"
}Ready to set up a webhook?
Fork our Node.js with Express, Node.js with Fastify or Python examples, deploy them, and add the webhook to your form.
If you want to create webhooks via API, first, get your access token. If you already have your access token, check out the Webhooks walkthroughs or reference documentation.