> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://typeform.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://typeform.ferndocs.com/_mcp/server.

# Example Webhook Payload

> Detailed examples of webhook payloads for every Typeform field type to help you parse and process response data.

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:

```json
{
  "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:**

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

**Answer:**

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

### Email

**Field definition:**

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

**Answer:**

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

### Website / URL

**Field definition:**

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

**Answer:**

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

### Phone number

**Field definition:**

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

**Answer:**

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

### Number

**Field definition:**

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

**Answer:**

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

### Multiple choice (single selection)

**Field definition:**

```json
{
  "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:**

```json
{
  "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):**

```json
{
  "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:**

```json
{
  "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:**

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

### Dropdown

**Field definition:**

```json
{
  "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:**

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

### Yes/No

**Field definition:**

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

**Answer (Yes):**

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

**Answer (No):**

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

### Opinion scale

**Field definition:**

```json
{
  "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:**

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

### Rating

**Field definition:**

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

**Answer:**

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

### Date

**Field definition:**

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

**Answer:**

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

### File upload

**Field definition:**

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

**Answer:**

```json
{
  "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:**

```json
{
  "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:**

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

### Legal consent

**Field definition:**

```json
{
  "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:**

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

### Payment

**Field definition:**

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

**Answer (successful):**

```json
{
  "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):**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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:

```javascript
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

* Set up [webhook security](/webhooks-api/secure-webhooks)
* Learn about [webhook implementation](/webhooks-api/walkthroughs)
* See the [API Reference](/api-reference) for webhook endpoints