Tally Webhook

Tally Webhook

Each stored delivery is one Tally FORM_RESPONSE JSON body — one form submission. Tools read what already landed; there is no pull API and no way to submit or edit forms from here.

Tally payload shape (export.json)

Top level:

• eventType — always FORM_RESPONSE (the only event type).
• createdAt — when Tally recorded the submission (ISO 8601).
• eventId — delivery id when present; useful when comparing retries.
• data — submission envelope:
  • responseId / submissionId — stable ids for the same answer; prefer these when deduping.
  • respondentId, formId, formName — who submitted and which form.
  • fields — array of answered questions; answers live here, not at the top level.

Each element of data.fields:

• key — stable question id (often question_*); map answers by key when labels repeat.
• label — question title shown to the respondent.
• type — input kind (INPUT_TEXT, INPUT_EMAIL, TEXTAREA, DROPDOWN, MULTIPLE_CHOICE, CHECKBOXES, LINEAR_SCALE, FILE_UPLOAD, HIDDEN_FIELDS, PAYMENT, and others).
• value — submitted answer; shape depends on type:
  • Text-like types — string.
  • Choice types — often an array of option ids; pair with options (id + text) for human-readable labels.
  • FILE_UPLOAD — array of { name, url, id } objects (signed URLs; may expire).
  • HIDDEN_FIELDS — string values (UTM params, referrer tokens, prefill data).
• options — present on choice fields; translate value ids to display text.

Field keys, labels, types, and option sets vary per form — inspect the latest JSON rather than assuming a fixed schema.

First moves

1. Latest report — default for “what did the last respondent submit” or summarising recent leads.
2. Report freshness — compare source.captured_at (when ingest stored the POST) with export.json.createdAt (when Tally recorded the submission).
3. Recent reports — scan history for volume, duplicate responseIds, or submissions from a date range.
4. One report by id — after listing, when the user points at a specific delivery.

Stored response shape

• export.json — parsed Tally webhook object (structure above).
• export.text — raw body when JSON is large or parsing fell back.
• source — captured_at, filename, format, connection purpose.

Walk data.fields to answer field-level questions. For choice questions, resolve option ids through options before quoting labels to the user.

Operational order

1. Start with the latest report — do not guess a report id.
2. If captured_at is older than expected, say so — submissions arrive when respondents submit upstream.
3. List recent reports only for history, duplicate suspicion, or explicit compare-by-date asks.
4. Read ## This connection in the skill supplement for form-specific field notes.

Gotchas

• Read-only — cannot submit forms, edit responses, or replay webhooks from here.
• Answers in data.fields — do not look for answers at the top level of the JSON.
• Variable forms — each connection may receive a different form; keys and labels differ.
• Choice values — value may be option ids, not display text; use options.
• Retries / duplicates — the same submission may land more than once; compare data.responseId or data.submissionId across recent deliveries.
• Hidden fields — UTM and tracking values often appear as HIDDEN_FIELDS entries with generic labels like hidden_fields.
• File uploads — URLs in FILE_UPLOAD values may be time-limited; treat as snapshots at capture time.
• Empty — no stored reports means nothing has arrived yet; say no submission is available.