Skip to navigation

Example Webhook Payload

Complete webhook payload examples for all field types

This guide provides complete examples of webhook payloads for all Typeform field types, helping you understand how to parse and process incoming webhook data.

Complete payload structure

Here’s a full webhook payload with multiple field types:

{
  "event_id": "01HKMN8VCFX1ABC123XYZ789",
  "event_type": "form_response",
  "form_response": {
    "form_id": "abc123xyz",
    "token": "abc123xyz789",
    "landed_at": "2024-01-15T10:30:00Z",
    "submitted_at": "2024-01-15T10:35:25Z",
    "calculated": {
      "score": 85
    },
    "hidden": {
      "user_id": "12345",
      "source": "email_campaign",
      "utm_source": "newsletter",
      "utm_medium": "email"
    },
    "definition": {
      "id": "abc123xyz",
      "title": "Customer Feedback Survey 2024",
      "fields": [
        {
          "id": "field_name",
          "title": "What's your name?",
          "type": "short_text",
          "ref": "customer_name",
          "properties": {}
        },
        {
          "id": "field_email",
          "title": "What's your email?",
          "type": "email",
          "ref": "customer_email",
          "properties": {}
        },
        {
          "id": "field_satisfaction",
          "title": "How satisfied are you with our service?",
          "type": "opinion_scale",
          "ref": "satisfaction_score",
          "properties": {
            "steps": 10,
            "start_at_one": true,
            "labels": {
              "left": "Not satisfied",
              "right": "Very satisfied"
            }
          }
        }
      ]
    },
    "answers": [
      {
        "type": "text",
        "text": "John Smith",
        "field": {
          "id": "field_name",
          "type": "short_text",
          "ref": "customer_name"
        }
      },
      {
        "type": "email",
        "email": "john.smith@example.com",
        "field": {
          "id": "field_email",
          "type": "email",
          "ref": "customer_email"
        }
      },
      {
        "type": "number",
        "number": 9,
        "field": {
          "id": "field_satisfaction",
          "type": "opinion_scale",
          "ref": "satisfaction_score"
        }
      }
    ]
  }
}

Answer types by field

Short text / Long text

Field definition:

{
  "id": "field_name",
  "title": "What's your name?",
  "type": "short_text",
  "ref": "name"
}

Answer:

{
  "type": "text",
  "text": "John Smith",
  "field": {
    "id": "field_name",
    "type": "short_text",
    "ref": "name"
  }
}

Email

Field definition:

{
  "id": "field_email",
  "title": "Your email address",
  "type": "email",
  "ref": "email"
}

Answer:

{
  "type": "email",
  "email": "user@example.com",
  "field": {
    "id": "field_email",
    "type": "email",
    "ref": "email"
  }
}

Website / URL

Field definition:

{
  "id": "field_website",
  "title": "Your website",
  "type": "website",
  "ref": "website"
}

Answer:

{
  "type": "url",
  "url": "https://example.com",
  "field": {
    "id": "field_website",
    "type": "website",
    "ref": "website"
  }
}

Phone number

Field definition:

{
  "id": "field_phone",
  "title": "Your phone number",
  "type": "phone_number",
  "ref": "phone"
}

Answer:

{
  "type": "phone_number",
  "phone_number": "+1-555-123-4567",
  "field": {
    "id": "field_phone",
    "type": "phone_number",
    "ref": "phone"
  }
}

Number

Field definition:

{
  "id": "field_employees",
  "title": "How many employees?",
  "type": "number",
  "ref": "employee_count",
  "properties": {
    "separator": ",",
    "description": "Please enter a whole number"
  }
}

Answer:

{
  "type": "number",
  "number": 150,
  "field": {
    "id": "field_employees",
    "type": "number",
    "ref": "employee_count"
  }
}

Multiple choice (single selection)

Field definition:

{
  "id": "field_product",
  "title": "Which product are you interested in?",
  "type": "multiple_choice",
  "ref": "product_interest",
  "properties": {
    "randomize": false,
    "allow_multiple_selection": false,
    "allow_other_choice": true,
    "vertical_alignment": true,
    "choices": [
      {
        "id": "choice_a",
        "ref": "product_a",
        "label": "Product A"
      },
      {
        "id": "choice_b",
        "ref": "product_b",
        "label": "Product B"
      },
      {
        "id": "choice_c",
        "ref": "product_c",
        "label": "Product C"
      }
    ]
  }
}

Answer:

{
  "type": "choice",
  "choice": {
    "id": "choice_b",
    "ref": "product_b",
    "label": "Product B"
  },
  "field": {
    "id": "field_product",
    "type": "multiple_choice",
    "ref": "product_interest"
  }
}

Answer (with “Other” option):

{
  "type": "choice",
  "choice": {
    "other": "Custom solution we're looking for"
  },
  "field": {
    "id": "field_product",
    "type": "multiple_choice",
    "ref": "product_interest"
  }
}

Multiple choice (multiple selections)

Field definition:

{
  "id": "field_interests",
  "title": "What topics interest you? (select all that apply)",
  "type": "multiple_choice",
  "ref": "interests",
  "properties": {
    "allow_multiple_selection": true,
    "choices": [
      {
        "id": "choice_design",
        "ref": "design",
        "label": "Design"
      },
      {
        "id": "choice_dev",
        "ref": "development",
        "label": "Development"
      },
      {
        "id": "choice_marketing",
        "ref": "marketing",
        "label": "Marketing"
      }
    ]
  }
}

Answer:

{
  "type": "choices",
  "choices": {
    "ids": ["choice_design", "choice_dev"],
    "refs": ["design", "development"],
    "labels": ["Design", "Development"]
  },
  "field": {
    "id": "field_interests",
    "type": "multiple_choice",
    "ref": "interests"
  }
}

Field definition:

{
  "id": "field_country",
  "title": "Which country are you from?",
  "type": "dropdown",
  "ref": "country",
  "properties": {
    "alphabetical_order": true,
    "choices": [
      {
        "id": "choice_us",
        "ref": "usa",
        "label": "United States"
      },
      {
        "id": "choice_uk",
        "ref": "uk",
        "label": "United Kingdom"
      },
      {
        "id": "choice_ca",
        "ref": "canada",
        "label": "Canada"
      }
    ]
  }
}

Answer:

{
  "type": "choice",
  "choice": {
    "id": "choice_us",
    "ref": "usa",
    "label": "United States"
  },
  "field": {
    "id": "field_country",
    "type": "dropdown",
    "ref": "country"
  }
}

Yes/No

Field definition:

{
  "id": "field_subscribe",
  "title": "Would you like to subscribe to our newsletter?",
  "type": "yes_no",
  "ref": "newsletter_subscription"
}

Answer (Yes):

{
  "type": "boolean",
  "boolean": true,
  "field": {
    "id": "field_subscribe",
    "type": "yes_no",
    "ref": "newsletter_subscription"
  }
}

Answer (No):

{
  "type": "boolean",
  "boolean": false,
  "field": {
    "id": "field_subscribe",
    "type": "yes_no",
    "ref": "newsletter_subscription"
  }
}

Opinion scale

Field definition:

{
  "id": "field_nps",
  "title": "How likely are you to recommend us?",
  "type": "opinion_scale",
  "ref": "nps_score",
  "properties": {
    "steps": 11,
    "start_at_one": false,
    "labels": {
      "left": "Not likely",
      "center": "Neutral",
      "right": "Very likely"
    }
  }
}

Answer:

{
  "type": "number",
  "number": 9,
  "field": {
    "id": "field_nps",
    "type": "opinion_scale",
    "ref": "nps_score"
  }
}

Rating

Field definition:

{
  "id": "field_rating",
  "title": "How would you rate your experience?",
  "type": "rating",
  "ref": "experience_rating",
  "properties": {
    "steps": 5,
    "shape": "star"
  }
}

Answer:

{
  "type": "number",
  "number": 4,
  "field": {
    "id": "field_rating",
    "type": "rating",
    "ref": "experience_rating"
  }
}

Date

Field definition:

{
  "id": "field_date",
  "title": "When did this occur?",
  "type": "date",
  "ref": "incident_date",
  "properties": {
    "separator": "/",
    "structure": "MMDDYYYY"
  }
}

Answer:

{
  "type": "date",
  "date": "2024-03-15",
  "field": {
    "id": "field_date",
    "type": "date",
    "ref": "incident_date"
  }
}

File upload

Field definition:

{
  "id": "field_resume",
  "title": "Please upload your resume",
  "type": "file_upload",
  "ref": "resume",
  "properties": {
    "description": "PDF or Word document only"
  }
}

Answer:

{
  "type": "file_url",
  "file_url": "https://api.typeform.com/forms/abc123/responses/xyz789/fields/field_resume/files/resume.pdf",
  "field": {
    "id": "field_resume",
    "type": "file_upload",
    "ref": "resume"
  }
}

Picture choice

Field definition:

{
  "id": "field_style",
  "title": "Choose your preferred style",
  "type": "picture_choice",
  "ref": "style_preference",
  "properties": {
    "show_labels": true,
    "multiple_selection": false,
    "choices": [
      {
        "id": "choice_modern",
        "ref": "modern",
        "label": "Modern",
        "image": {
          "id": "img_abc123",
          "href": "https://images.typeform.com/images/abc123"
        }
      },
      {
        "id": "choice_classic",
        "ref": "classic",
        "label": "Classic",
        "image": {
          "id": "img_def456",
          "href": "https://images.typeform.com/images/def456"
        }
      }
    ]
  }
}

Answer:

{
  "type": "choice",
  "choice": {
    "id": "choice_modern",
    "ref": "modern",
    "label": "Modern"
  },
  "field": {
    "id": "field_style",
    "type": "picture_choice",
    "ref": "style_preference"
  }
}

Field definition:

{
  "id": "field_terms",
  "title": "I agree to the terms and conditions",
  "type": "legal",
  "ref": "terms_agreement",
  "properties": {
    "description": "By checking this box, you agree to our Terms of Service and Privacy Policy"
  }
}

Answer:

{
  "type": "boolean",
  "boolean": true,
  "field": {
    "id": "field_terms",
    "type": "legal",
    "ref": "terms_agreement"
  }
}

Payment

Field definition:

{
  "id": "field_payment",
  "title": "Payment",
  "type": "payment",
  "ref": "payment",
  "properties": {
    "description": "Complete your purchase",
    "currency": "USD",
    "price": {
      "type": "variable",
      "value": "product_selection"
    }
  }
}

Answer (successful):

{
  "type": "payment",
  "payment": {
    "amount": "99.99",
    "last4": "4242",
    "name": "John Smith",
    "success": true,
    "currency": "USD",
    "transaction_id": "ch_1ABC123XYZ789"
  },
  "field": {
    "id": "field_payment",
    "type": "payment",
    "ref": "payment"
  }
}

Answer (failed):

{
  "type": "payment",
  "payment": {
    "amount": "99.99",
    "success": false,
    "currency": "USD",
    "error_message": "Card declined"
  },
  "field": {
    "id": "field_payment",
    "type": "payment",
    "ref": "payment"
  }
}

Ranking

Field definition:

{
  "id": "field_priorities",
  "title": "Rank these features by importance",
  "type": "ranking",
  "ref": "feature_priorities",
  "properties": {
    "choices": [
      {
        "id": "choice_speed",
        "ref": "speed",
        "label": "Speed"
      },
      {
        "id": "choice_quality",
        "ref": "quality",
        "label": "Quality"
      },
      {
        "id": "choice_price",
        "ref": "price",
        "label": "Price"
      }
    ]
  }
}

Answer:

{
  "type": "choices",
  "choices": {
    "ids": ["choice_quality", "choice_speed", "choice_price"],
    "refs": ["quality", "speed", "price"],
    "labels": ["Quality", "Speed", "Price"]
  },
  "field": {
    "id": "field_priorities",
    "type": "ranking",
    "ref": "feature_priorities"
  }
}

Parsing webhook data

Here’s a helper function to parse all answer types:

function parseWebhookPayload(payload) {
  const { form_response } = payload;
  const parsed = {
    eventId: payload.event_id,
    formId: form_response.form_id,
    responseToken: form_response.token,
    submittedAt: new Date(form_response.submitted_at),
    score: form_response.calculated?.score,
    hiddenFields: form_response.hidden || {},
    answers: {},
  };
  // Parse each answer
  for (const answer of form_response.answers) {
    const ref = answer.field.ref;
    switch (answer.type) {
      case 'text':
      case 'email':
      case 'url':
      case 'phone_number':
        parsed.answers[ref] = answer[answer.type];
        break;
      case 'number':
        parsed.answers[ref] = answer.number;
        break;
      case 'boolean':
        parsed.answers[ref] = answer.boolean;
        break;
      case 'date':
        parsed.answers[ref] = new Date(answer.date);
        break;
      case 'choice':
        if (answer.choice.other) {
          parsed.answers[ref] = {
            type: 'other',
            value: answer.choice.other,
          };
        } else {
          parsed.answers[ref] = answer.choice.label;
        }
        break;
      case 'choices':
        parsed.answers[ref] = answer.choices.labels;
        break;
      case 'file_url':
        parsed.answers[ref] = answer.file_url;
        break;
      case 'payment':
        parsed.answers[ref] = {
          success: answer.payment.success,
          amount: parseFloat(answer.payment.amount),
          currency: answer.payment.currency,
          transactionId: answer.payment.transaction_id,
        };
        break;
    }
  }
  return parsed;
}
// Usage
app.post('/webhooks/typeform', (req, res) => {
  const parsed = parseWebhookPayload(req.body);
  console.log(parsed);
  // {
  //   eventId: '01HKMN8VCFX1ABC123XYZ789',
  //   formId: 'abc123xyz',
  //   responseToken: 'abc123xyz789',
  //   submittedAt: Date,
  //   score: 85,
  //   hiddenFields: { user_id: '12345', source: 'email' },
  //   answers: {
  //     customer_name: 'John Smith',
  //     customer_email: 'john.smith@example.com',
  //     satisfaction_score: 9
  //   }
  // }
  res.status(200).send('OK');
});

Next steps