웹훅

웹훅 켜기

폼을 열고 설정 탭으로 가서 웹훅을 켜세요. 응답을 받을 주소를 붙여 넣으면, 입력을 멈춘 잠시 뒤 Fillio가 저장하고 화면에서 확인해 줍니다. 폼마다 주소는 하나이며, 스위치를 다시 끄면 주소가 지워집니다.

주소는 HTTPS여야 합니다

Fillio는 https://로 시작하는 주소만 호출합니다. http:// 주소도 설정 필드에는 입력되지만 결코 호출되지 않으므로, 저장된 것처럼 보이는 웹훅이 아무것도 전달하지 않고 조용히 넘어갑니다.

사설망을 가리키는 주소도 거부됩니다. 10.x, 127.x, 169.254.x, 172.16-31.x, 192.168.x 대역의 호스트, 모든 IPv6 주소, localhost이거나 .local 또는 .internal로 끝나는 이름이 여기에 해당합니다. 엔드포인트는 공개 인터넷에서 닿을 수 있어야 합니다.

요청

JSON 본문이 담긴 POST입니다. 헤더 네 개가 함께 갑니다.

페이로드

이벤트를 설명하는 봉투와, 응답을 설명하는 data 객체.

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

fields 안에는

모든 항목이 네 가지 속성을 담고, 옵션이 있는 질문은 다섯 번째를 하나 더 담습니다.

답변된 질문만 도착합니다

응답자가 건드리지 않은 질문은 빈 값으로 전송되는 대신 배열에서 아예 빠지고, 조건부 로직으로 숨겨진 질문은 처음부터 나타나지 않습니다. 순서나 고정된 항목 수에 기대지 말고 key로 각 답변을 찾으세요.

선택형 답변은 라벨이 아니라 ID를 담습니다

드롭다운이나 객관식 답변은 선택된 옵션의 ID이고, 체크박스·다중 선택·순위 답변은 옵션 ID의 배열입니다. 같은 항목에 담긴 options 목록과 대조해 풀어내세요. 순위 답변은 응답자가 매긴 순서를 그대로 지킵니다.

기타 옵션

응답자가 기타 입력란에 직접 쓰면, 값은 옵션 ID가 아니라 __OTHER__: 뒤에 입력한 내용이 붙은 텍스트가 됩니다. 이 접두사를 떼어 내면 답변을 읽을 수 있습니다.

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

파일과 서명

파일 업로드 답변은 Fillio 스토리지에 있는 파일의 다운로드 링크입니다. 서명 답변은 base64 PNG 데이터 URL이라 그대로 저장하거나 표시할 수 있습니다.

필드 유형

유형은 변하지 않는 공개 이름이므로 Fillio 내부의 변경이 연동에 닿는 일은 없습니다. Fillio가 매핑하지 못하는 것은 INPUT_TEXT로 도착합니다.

엔드포인트가 응답하지 않으면

Fillio는 10초를 기다립니다. 타임아웃, 연결 오류, 2xx 범위를 벗어난 모든 상태 코드는 전송 실패로 처리되고 거기서 끝입니다. 재시도도 없고, 다시 흘려보낼 큐도 없습니다.

응답 자체는 전혀 영향을 받지 않습니다. 요청을 보내기 전에 이미 저장되고 엔드포인트가 어떻게 되든 대시보드에 남으므로, 전송 하나를 잃어도 대시보드는 온전한 기록으로 남습니다.

서명은 없습니다

Fillio는 요청에 서명하지 않고 공유 비밀값도 보내지 않으므로, 본문만으로는 출처를 증명할 수 없습니다. 엔드포인트가 확신해야 한다면 나만 아는 주소를 주세요. 길고 알아맞히기 어려운 경로나 쿼리 문자열을 쓰고, 그 밖의 경로로 들어오는 것은 신뢰하지 마세요.

전송마다 고유한 이벤트 ID가 X-Fillio-Event-Id 헤더와 본문 양쪽에 담깁니다. 이미 처리한 ID를 기록해 두는 것이, 엔드포인트를 두 번 호출해도 안전하게 만드는 가장 간단한 방법입니다.