Webhook-Payloads

Jede NueForm-Webhook-Anfrage sendet eine JSON-Payload im Anfrage-Body. Diese Seite dokumentiert das vollständige Payload-Schema für jeden Ereignistyp.

Gemeinsame Struktur

Alle Webhook-Payloads teilen sich diese Felder auf oberster Ebene:

form.submitted-Payload

Diese Payload wird gesendet, wenn eine befragte Person eine vollständige Formularantwort übermittelt.

Vollständiges Beispiel

{
  "event": "form.submitted",
  "formId": "507f1f77bcf86cd799439011",
  "formTitle": "Customer Feedback Survey",
  "responseId": "507f1f77bcf86cd799439022",
  "answers": [
    {
      "questionId": "507f1f77bcf86cd799439033",
      "value": "Jane Doe"
    },
    {
      "questionId": "507f1f77bcf86cd799439044",
      "value": "jane@example.com"
    },
    {
      "questionId": "507f1f77bcf86cd799439055",
      "value": 4
    },
    {
      "questionId": "507f1f77bcf86cd799439066",
      "value": "The onboarding flow was smooth and intuitive."
    },
    {
      "questionId": "507f1f77bcf86cd799439077",
      "value": ["Feature A", "Feature C"]
    },
    {
      "questionId": "507f1f77bcf86cd799439088",
      "value": true
    }
  ],
  "respondent": {
    "id": "507f1f77bcf86cd799439016",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "auth_method": "sso"
  },
  "submittedAt": "2025-03-15T14:32:07.123Z"
}

Feldreferenz

Felder auf oberster Ebene

event --- string

Bei diesem Ereignistyp immer "form.submitted".

formId --- string

Die MongoDB-ObjectId des Formulars. Das ist ein 24-stelliger Hexadezimal-String.

formTitle --- string

Der menschenlesbare Titel des Formulars zum Zeitpunkt des Webhook-Versands. Beachte: Wenn du das Formular später umbenennst, enthalten bereits zugestellte Webhooks weiterhin den alten Titel.

responseId --- string

Die MongoDB-ObjectId der gespeicherten Response. Damit kannst du die vollständige Response über die Responses-API abrufen oder sie als Idempotenzschlüssel zum Deduplizieren von Webhook-Zustellungen verwenden.

submittedAt --- string

ISO-8601-Zeitstempel, der angibt, wann der Webhook versendet wurde. Er wird zum Versandzeitpunkt erzeugt und liegt sehr nah am submittedAt-Feld der Response in der Datenbank (ist aber nicht zwingend identisch).

respondent --- object oder null

Identität des angemeldeten Benutzers, der die Response übermittelt hat — nur enthalten, wenn das Formular einen Login erforderte (requireLogin: true). null bei allen anonymen Übermittlungen. Das vollständige Schema und Verhalten findest du unten unter Identität der Befragten.

Antwortobjekte

Jeder Eintrag im answers-Array steht für die Antwort auf eine einzelne Frage:

Antwortwerte nach Fragetyp

Das value-Feld in jedem Antwortobjekt hängt vom Fragetyp ab. Hier ist das Format für jeden Typ:

Texteingaben

Auswahlfragen

Bewertungsfragen

Datum und Uhrzeit

Das Format des Datums-Strings entspricht der dateFormat-Eigenschaft der Frage (Standard: YYYY-MM-DD).

Rechtliches und Hinweistexte

Ranking

Das Array spiegelt die von der befragten Person gewählte Reihenfolge wider, vom ersten bis zum letzten Platz.

Matrix

Das Objekt ordnet jeder Zeilenbeschriftung die gewählte Spaltenbeschriftung zu.

Datei-Upload

Der Wert ist die URL der hochgeladenen Datei im NueForm-Speicher.

Unterschrift und Zeichnung

Beide liefern eine base64-codierte PNG-Data-URI des erfassten Bildes.

Aufnahme

Der Wert ist die URL der hochgeladenen Aufnahmedatei.

Zusammengesetzte Fragen

Zusammengesetzte Fragetypen (contact_info, address, question_group, multi_question_page) erzeugen mehrere Antworteinträge im answers-Array --- einen pro Teilfeld. Jede Teilfeld-Antwort verwendet die eigene questionId des Teilfelds.

Eine contact_info-Frage könnte zum Beispiel Folgendes erzeugen:

[
  { "questionId": "first_name", "value": "Jane" },
  { "questionId": "last_name", "value": "Doe" },
  { "questionId": "email", "value": "jane@example.com" },
  { "questionId": "phone_number", "value": "+1 555-0100" },
  { "questionId": "company", "value": "Acme Inc." }
]

Identität der Befragten

Wenn ein Formular mit requireLogin: true konfiguriert ist, ist jede angenommene Übermittlung an einen angemeldeten Benutzer gebunden. Webhook-Payloads legen diese Identität den Formularbesitzern über das respondent-Feld offen. Bei allen anderen Übermittlungen ist das Feld null.

Schema

{
  "respondent": {
    "id": "507f1f77bcf86cd799439016",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "auth_method": "sso"
  }
}

Wann respondent befüllt ist

respondent ist nur befüllt, wenn:

1. das Formular requireLogin auf true gesetzt hat, und
2. die übermittelnde Person sich vor dem Absenden angemeldet hat, weil das Formular es verlangte.

Wenn zusätzlich requireSsoLogin auf true steht, erreichen nur Benutzer den Absende-Schritt, die per SSO Mitglied des Formular-Teams sind — jedes befüllte respondent-Objekt hat dann auth_method: "sso".

Wann respondent null ist

Das Feld ist für berechenbares Parsen immer im JSON vorhanden und ist null, sobald einer dieser Punkte zutrifft:

• Das Formular erforderte keinen Login (requireLogin war false).
• Die übermittelnde Person war anonym.
• Die Response wurde über den Einwilligungs-Flow nach dem Absenden gespeichert (die Aufforderung „Diese Antwort übernehmen"). Per Einwilligung gespeicherte Responses erscheinen in Webhook-Payloads niemals mit Identität — sie werden nur in der „Meine Antworten"-Ansicht der Person gespeichert und nicht an Webhook-Empfänger weitergegeben.

Quiz-Ergebnisse

Bei Formularen in einem Quiz-Modus (knowledge_quiz, lead_qualification oder match_quiz) enthält die gespeicherte Response ein quizResults-Objekt. Dieses Objekt ist nicht direkt in der Webhook-Payload enthalten, du kannst es aber über die Responses-API mit der responseId aus dem Webhook abrufen.

Das quizResults-Objekt hat folgende Struktur:

{
  "formMode": "knowledge_quiz",
  "score": 7,
  "correctAnswers": 7,
  "totalScorableQuestions": 10,
  "maxScore": 10,
  "matchedEndingId": "507f1f77bcf86cd799439099"
}

Metadaten

Die gespeicherte Response kann außerdem ein metadata-Objekt mit versteckten Feldern enthalten, die über URL-Parameter übergeben wurden. Diese sind über die Responses-API verfügbar, aber nicht Teil der Webhook-Payload.

{
  "hiddenFields": {
    "utm_source": "google",
    "utm_campaign": "spring_sale",
    "user_id": "ext_12345"
  }
}

Um die Metadaten einer per Webhook zugestellten Response abzurufen, hole sie über die responseId:

curl https://app.nueform.com/api/v1/forms/FORM_ID/responses/RESPONSE_ID \
  -H "Authorization: Bearer nf_your_api_key"

HTTP-Header

Jede Webhook-Anfrage enthält diese HTTP-Header:

Wie du die Signatur validierst, erfährst du unter Verifizierung.

Payload-Größe

Webhook-Payloads sind in der Regel klein (unter 10 KB). Die Größe hängt vor allem von der Anzahl der Fragen und der Länge der Textantworten ab. Datei-Upload-Antworten enthalten URLs (keine Dateiinhalte) und vergrößern die Payload daher kaum.

Nächste Schritte

• Verifizierung --- Webhook-Signaturen validieren
• Testen --- Webhook-Payloads lokal testen
• Ereignisse --- Ereignistypen und Zustellgarantien