Webhooks

Een webhook aanzetten

Open het formulier, ga naar het tabblad Instellingen en zet Webhook aan. Plak het adres dat de inzendingen moet ontvangen; Fillio slaat het een moment nadat u stopt met typen op en bevestigt dat op het scherm. Elk formulier draagt één adres, en de schakelaar weer uitzetten wist het.

Het adres moet HTTPS zijn

Fillio roept alleen adressen aan die met https:// beginnen. Een http://-adres wordt door het instellingenveld geaccepteerd maar nooit aangeroepen, dus een webhook die opgeslagen lijkt, levert stilletjes niets af.

Adressen die naar een privénetwerk wijzen worden eveneens geweigerd: elke host op 10.x, 127.x, 169.254.x, 172.16-31.x of 192.168.x, elk IPv6-adres, en elke naam die localhost is of eindigt op .local of .internal. Uw endpoint moet bereikbaar zijn vanaf het publieke internet.

Het verzoek

Een POST met een JSON-body. Er reizen vier headers mee.

De payload

Een envelop die de gebeurtenis beschrijft, en een data-object dat de reactie beschrijft.

{
  "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
      }
    ]
  }
}

In fields

Elk item draagt vier eigenschappen, en een vraag met opties draagt er een vijfde.

Alleen beantwoorde vragen komen binnen

Een vraag die de respondent onaangeroerd liet, ontbreekt in de array in plaats van als lege waarde te worden verstuurd, en een vraag die door voorwaardelijke logica verborgen is, verschijnt helemaal niet. Zoek elk antwoord op via zijn key in plaats van te vertrouwen op de positie of op een vast aantal items.

Keuzeantwoorden dragen ID's, geen labels

Een antwoord op een dropdown of meerkeuzevraag is de ID van de gekozen optie, en een antwoord op selectievakjes, multiselect of rangschikking is een array van optie-ID's. Zoek ze op in de optielijst van datzelfde item. Een rangschikkingsantwoord behoudt de volgorde waarin de respondent de items heeft gezet.

De optie Anders

Wanneer een respondent in een Anders-veld schrijft, is de waarde geen optie-ID maar de tekst __OTHER__: gevolgd door wat er getypt is. Haal dat voorvoegsel weg om het antwoord te lezen.

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

Bestanden en handtekeningen

Een antwoord op een bestandsupload is een downloadlink naar het bestand in de opslag van Fillio. Een handtekeningantwoord is een base64-PNG-data-URL, die u direct kunt opslaan of weergeven.

Veldtypen

Het type is een stabiele publieke naam, dus een verandering binnen Fillio bereikt uw integratie nooit. Alles wat Fillio niet kan toewijzen, komt binnen als INPUT_TEXT.

Als uw endpoint niet antwoordt

Fillio wacht tien seconden. Een time-out, een verbindingsfout of een status buiten het 2xx-bereik telt als een mislukte aflevering, en daarmee houdt het op: er is geen nieuwe poging en geen wachtrij om opnieuw af te spelen.

De reactie zelf wordt nooit geraakt. Hij wordt opgeslagen voordat het verzoek wordt gedaan en blijft in uw dashboard staan, wat uw endpoint ook doet, zodat het dashboard het volledige archief blijft, ook als een aflevering verloren gaat.

Er is geen handtekening

Fillio ondertekent het verzoek niet en stuurt geen gedeeld geheim mee, dus de body alleen bewijst niet waar hij vandaan komt. Moet uw endpoint zeker zijn, geef het dan een adres dat alleen u kent: een lang, onraadbaar pad of query string. Behandel alles wat elders binnenkomt als onbetrouwbaar.

Elke aflevering draagt een eigen event-ID, zowel in de header X-Fillio-Event-Id als in de body. De ID's bijhouden die u al hebt afgehandeld is de eenvoudigste manier om uw endpoint veilig twee keer aanroepbaar te maken.