Webhooks

Einen Webhook einschalten

Öffnen Sie das Formular, gehen Sie auf den Tab Einstellungen und schalten Sie Webhook ein. Fügen Sie die Adresse ein, die die Einsendungen empfangen soll; Fillio speichert sie kurz nachdem Sie aufhören zu tippen und bestätigt es auf dem Bildschirm. Jedes Formular führt eine Adresse, und den Schalter wieder auszuschalten löscht sie.

Die Adresse muss HTTPS sein

Fillio ruft nur Adressen auf, die mit https:// beginnen. Eine http://-Adresse wird vom Einstellungsfeld angenommen, aber nie aufgerufen. Ein scheinbar gespeicherter Webhook liefert dann stillschweigend nichts.

Adressen, die in ein privates Netz zeigen, werden ebenfalls abgelehnt: jeder Host auf 10.x, 127.x, 169.254.x, 172.16-31.x oder 192.168.x, jede IPv6-Adresse und jeder Name, der localhost lautet oder auf .local oder .internal endet. Ihr Endpunkt muss aus dem öffentlichen Internet erreichbar sein.

Die Anfrage

Ein POST mit einem JSON-Body. Vier Header reisen mit.

Der Payload

Ein Umschlag, der das Event beschreibt, und ein data-Objekt, das die Antwort beschreibt.

{
  "eventId": "8f2c1d7a-4b09-4e5c-9a13-6d0f8b2e77c4",
  "eventType": "FORM_RESPONSE",
  "createdAt": "2026-08-26T09:14:22.481Z",
  "data": {
    "responseId": "Qh3Rk9wZm1sVtY7cN2xP",
    "formId": "7bTn4Kq2Wx",
    "formName": "Workshop signup",
    "createdAt": "2026-08-26T09:14:22.481Z",
    "fields": [
      {
        "key": "V1StGXR8_Z5jdHi6B-myT",
        "label": "Full name",
        "type": "INPUT_TEXT",
        "value": "Mira Kaya"
      },
      {
        "key": "kM4pQz7LxAe2Rn0BsTvUw",
        "label": "Which session?",
        "type": "MULTIPLE_CHOICE",
        "value": "c9XbNf3JdQ",
        "options": [
          { "id": "c9XbNf3JdQ", "text": "Morning" },
          { "id": "eR2mYt8KpL", "text": "Afternoon" }
        ]
      },
      {
        "key": "zA6cWn1FyH4tXd9QrLbEs",
        "label": "How likely are you to recommend us?",
        "type": "LINEAR_SCALE",
        "value": 9
      }
    ]
  }
}

Innerhalb von fields

Jeder Eintrag trägt vier Eigenschaften, eine Frage mit Optionen eine fünfte.

Es kommen nur beantwortete Fragen an

Eine Frage, die der Teilnehmer nicht angerührt hat, fehlt im Array, statt als leerer Wert gesendet zu werden, und eine per bedingter Logik ausgeblendete Frage taucht gar nicht auf. Schlagen Sie jede Antwort über ihren key nach, statt sich auf die Position oder eine feste Anzahl von Einträgen zu verlassen.

Auswahlantworten tragen IDs, keine Beschriftungen

Eine Dropdown- oder Multiple-Choice-Antwort ist die ID der gewählten Option; eine Checkbox-, Mehrfachauswahl- oder Rangfolge-Antwort ist ein Array von Options-IDs. Lösen Sie sie über die options-Liste desselben Eintrags auf. Eine Rangfolge-Antwort behält die Reihenfolge, in die der Teilnehmer die Einträge gebracht hat.

Die Option Sonstiges

Wenn ein Teilnehmer in ein Sonstiges-Feld schreibt, ist der Wert keine Options-ID, sondern der Text __OTHER__: gefolgt von dem, was er getippt hat. Entfernen Sie dieses Präfix, um die Antwort zu lesen.

"value": "__OTHER__:Heard about it from a friend"

Dateien und Unterschriften

Eine Datei-Upload-Antwort ist ein Download-Link auf die Datei in Fillios Speicher. Eine Unterschrift ist eine base64-PNG-Data-URL, die Sie direkt speichern oder anzeigen können.

Feldtypen

Der Typ ist ein stabiler öffentlicher Name, sodass eine Änderung innerhalb von Fillio Ihre Integration nie erreicht. Alles, was Fillio nicht zuordnen kann, kommt als INPUT_TEXT an.

Wenn Ihr Endpunkt nicht antwortet

Fillio wartet zehn Sekunden. Ein Timeout, ein Verbindungsfehler oder ein Status außerhalb des 2xx-Bereichs gilt als fehlgeschlagene Zustellung, und damit ist es vorbei: Es gibt keinen zweiten Versuch und keine Warteschlange zum Nachspielen.

Die Antwort selbst ist davon nie betroffen. Sie wird gespeichert, bevor die Anfrage abgeht, und bleibt in Ihrem Dashboard, was auch immer Ihr Endpunkt tut. Das Dashboard bleibt also die vollständige Aufzeichnung, selbst wenn eine Zustellung verloren geht.

Es gibt keine Signatur

Fillio signiert die Anfrage nicht und sendet kein gemeinsames Geheimnis. Der Body allein beweist also nicht, woher er kommt. Wenn Ihr Endpunkt sicher sein muss, geben Sie ihm eine Adresse, die nur Sie kennen: einen langen, nicht erratbaren Pfad oder Query-String. Alles, was anderswo eintrifft, behandeln Sie als nicht vertrauenswürdig.

Jede Zustellung trägt ihre eigene Event-ID, sowohl im Header X-Fillio-Event-Id als auch im Body. Sich zu merken, welche Sie schon verarbeitet haben, ist der einfachste Weg, Ihren Endpunkt gegen einen zweiten Aufruf abzusichern.