Webhooki

Włączanie webhooka

Otwórz formularz, przejdź do karty Ustawienia i włącz Webhook. Wklej adres, który ma odbierać odpowiedzi; Fillio zapisze go chwilę po zakończeniu pisania i potwierdzi to na ekranie. Każdy formularz niesie jeden adres, a wyłączenie przełącznika kasuje go.

Adres musi być HTTPS

Fillio wywołuje wyłącznie adresy zaczynające się od https://. Adres http:// zostanie przyjęty przez pole ustawień, ale nigdy nie będzie wywołany, więc pozornie zapisany webhook po cichu nie dostarczy niczego.

Odrzucane są też adresy wskazujące wnętrze sieci prywatnej: każdy host w 10.x, 127.x, 169.254.x, 172.16-31.x lub 192.168.x, każdy adres IPv6 oraz każda nazwa localhost lub kończąca się na .local albo .internal. Endpoint musi być osiągalny z publicznego internetu.

Żądanie

POST z treścią JSON. Towarzyszą mu cztery nagłówki.

Ładunek

Koperta opisująca zdarzenie oraz obiekt data opisujący odpowiedź.

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

Wewnątrz fields

Każdy wpis niesie cztery właściwości, a pytanie z opcjami niesie piątą.

Docierają tylko pytania z odpowiedzią

Pytanie, którego respondent nie tknął, w ogóle nie występuje w tablicy, zamiast przyjść jako pusta wartość, a pytanie ukryte przez logikę warunkową nie pojawia się nigdy. Każdą odpowiedź wyszukuj po jej kluczu, zamiast polegać na pozycji albo na stałej liczbie wpisów.

Odpowiedzi wyboru niosą identyfikatory, nie etykiety

Odpowiedź z listy rozwijanej lub jednokrotnego wyboru to identyfikator wybranej opcji, a odpowiedź z pól wyboru, wielokrotnego wyboru lub rankingu to tablica identyfikatorów opcji. Rozwiązuj je na podstawie listy options z tego samego wpisu. Odpowiedź rankingowa zachowuje kolejność ustawioną przez respondenta.

Opcja Inne

Gdy respondent wpisze coś w pole Inne, wartością nie jest identyfikator opcji, lecz tekst __OTHER__: wraz z tym, co wpisał. Żeby odczytać odpowiedź, usuń ten przedrostek.

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

Pliki i podpisy

Odpowiedź z przesłanym plikiem to link do pobrania pliku z magazynu Fillio. Odpowiedź z podpisem to adres data URL z obrazem PNG w base64, który można zapisać albo wyświetlić bezpośrednio.

Typy pól

Typ jest stabilną nazwą publiczną, więc zmiana wewnątrz Fillio nigdy nie dociera do integracji. Wszystko, czego Fillio nie potrafi zmapować, przychodzi jako INPUT_TEXT.

Gdy endpoint nie odpowiada

Fillio czeka dziesięć sekund. Przekroczenie limitu czasu, błąd połączenia albo dowolny status spoza zakresu 2xx liczy się jako nieudana dostawa. I na tym koniec: nie ma ponowień ani kolejki do odtworzenia.

Sama odpowiedź nigdy na tym nie traci. Jest zapisywana przed wysłaniem żądania i zostaje w panelu niezależnie od tego, co zrobi endpoint, więc panel pozostaje kompletnym zapisem nawet wtedy, gdy dostawa przepadnie.

Nie ma podpisu

Fillio nie podpisuje żądania i nie wysyła wspólnego sekretu, więc sama treść nie dowodzi, skąd pochodzi. Jeśli endpoint musi mieć pewność, warto nadać mu adres, którego nikt inny nie zna: długą, nieodgadnioną ścieżkę albo parametr zapytania. Wszystko, co przychodzi gdzie indziej, traktuj jako niezaufane.

Każda dostawa niesie własny identyfikator zdarzenia, w nagłówku X-Fillio-Event-Id i w treści. Zapisywanie już obsłużonych identyfikatorów to najprostszy sposób, żeby endpoint bezpiecznie znosił dwukrotne wywołanie.