Typeform Webhook MCP Server

Typeform Webhook

Each stored delivery is one Typeform form_response webhook — a JSON envelope POSTed when someone submits a connected typeform. Tools read what already landed; there is no pull API and no way to submit, edit, or delete responses from here.

Payload shape

Typical deliveries look like:

Top-level envelope:

• event_type — almost always form_response for submission webhooks.
• event_id — unique id for this webhook delivery; use with form_response.token (response id) for deduplication across retries.

Inside form_response:

• form_id — which typeform produced the submission.
• token — unique response id (alias response_id on newer payloads).
• submitted_at / landed_at — ISO 8601 timestamps from Typeform (prefer these over ingest time when quoting when someone answered).
• definition — embedded form schema: title, fields[] with id, title, type, ref, and choice metadata. Use it to interpret answers without a separate schema copy.
• answers — only answered questions; skipped or logic-jumped fields are omitted. Order in the array is not question order — match by field.id or field.ref.
• hidden — key/value strings passed via URL hidden fields (campaign ids, user ids, etc.).
• variables — array of { key, type, text|number } custom variables set on the form.
• calculated.score — present when the form uses scoring.
• ending — which ending screen the respondent saw.

Answer field semantics

Each answers[] item has a type (answer shape) and a field object (id, type, optional ref). Match definition.fields to answers by field id or ref, then read the value from the type-specific key:

First moves

1. Latest report — default for “what submission arrived last”; read export.json and walk form_response.answers against form_response.definition.fields.
2. Classify the payload — confirm event_type is form_response, note form_id, token, and submitted_at before drilling into individual answers.
3. Recent reports — list when comparing submission volume, duplicate tokens, or scanning responses over time.
4. One report by id — after listing, when the user points at a specific stored delivery.

Response shape

• export.json — parsed webhook body (preferred for answer-level questions).
• export.text — raw body when JSON is large or parsing failed.
• source.captured_at — when the POST landed here; use form_response.submitted_at for respondent timing unless the user asks about ingest delay.

Operational order

1. Start with the latest report — do not guess a report id.
2. Confirm event_type and read form_response.token before treating two deliveries as duplicates.
3. Map answers through definition.fields (title + ref) instead of assuming fixed column names like email.
4. List recent reports only for history, duplicate suspicion, or explicit compare-by-date asks.
5. Read ## This connection in the skill supplement for form-specific refs, hidden field keys, and variable names.

Gotchas

• Read-only — cannot submit test responses, change form logic, or replay Typeform webhooks from here.
• Schema varies per form — each typeform embeds its own definition.fields; inspect the latest JSON instead of assuming a fixed lead schema.
• Partial answers — omitted answers entries mean skipped, hidden-by-logic, or unanswered; not data loss.
• Refs may be absent — field.ref appears only when the form author set readable refs; fall back to field.id and question titles from definition.
• Answer order is random — never assume array index matches question order.
• File uploads are URLs — file_url values point to Typeform-hosted files; fetch separately if binary content is needed.
• One response per delivery — each POST is one person's submission, not a batched export.