Webhook

Bật webhook

Mở biểu mẫu, vào tab Cài đặt và bật Webhook. Dán địa chỉ sẽ nhận các lượt gửi; Fillio lưu lại một lát sau khi bạn ngừng gõ và xác nhận ngay trên màn hình. Mỗi biểu mẫu mang một địa chỉ, và tắt công tắc đi sẽ xóa địa chỉ đó.

Địa chỉ bắt buộc phải là HTTPS

Fillio chỉ gọi những địa chỉ bắt đầu bằng https://. Địa chỉ http:// vẫn được ô cài đặt chấp nhận nhưng không bao giờ được gọi, nên một webhook trông như đã lưu sẽ âm thầm không gửi gì cả.

Các địa chỉ trỏ vào mạng nội bộ cũng bị từ chối: mọi host trên 10.x, 127.x, 169.254.x, 172.16-31.x hay 192.168.x, mọi địa chỉ IPv6, và mọi tên là localhost hoặc kết thúc bằng .local hay .internal. Endpoint của bạn phải truy cập được từ internet công cộng.

Yêu cầu

Một POST với phần thân JSON. Bốn header đi kèm theo nó.

Payload

Một lớp vỏ mô tả sự kiện, và một đối tượng data mô tả phản hồi.

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

Bên trong fields

Mỗi mục mang bốn thuộc tính, và câu hỏi có tùy chọn mang thêm thuộc tính thứ năm.

Chỉ những câu hỏi đã trả lời mới xuất hiện

Câu hỏi người trả lời bỏ trống sẽ vắng mặt khỏi mảng thay vì được gửi dưới dạng một giá trị rỗng, và câu hỏi bị logic điều kiện ẩn đi thì không bao giờ xuất hiện. Hãy tra từng câu trả lời theo key của nó thay vì dựa vào vị trí hay vào một số lượng mục cố định.

Câu trả lời lựa chọn mang ID, không phải nhãn

Câu trả lời của danh sách thả xuống hay trắc nghiệm là ID của tùy chọn được chọn, còn câu trả lời của hộp kiểm, chọn nhiều hay xếp hạng là một mảng ID tùy chọn. Hãy đối chiếu chúng với danh sách options trong cùng mục đó. Câu trả lời xếp hạng giữ nguyên thứ tự mà người trả lời đã sắp.

Tùy chọn Khác

Khi người trả lời viết vào ô Khác, giá trị không phải là ID tùy chọn mà là văn bản __OTHER__: theo sau là nội dung họ đã gõ. Hãy cắt bỏ tiền tố đó để đọc câu trả lời.

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

Tệp và chữ ký

Câu trả lời tải tệp lên là một liên kết tải xuống tệp nằm trong bộ nhớ của Fillio. Câu trả lời chữ ký là một data URL PNG dạng base64, bạn có thể lưu hoặc hiển thị trực tiếp.

Loại trường

Loại là một tên công khai ổn định, nên một thay đổi bên trong Fillio không bao giờ ảnh hưởng đến tích hợp của bạn. Bất cứ thứ gì Fillio không ánh xạ được sẽ đến dưới dạng INPUT_TEXT.

Nếu endpoint của bạn không trả lời

Fillio chờ mười giây. Hết thời gian chờ, lỗi kết nối hay bất kỳ mã trạng thái nào ngoài dải 2xx đều tính là một lần gửi thất bại, và mọi chuyện dừng ở đó: không có lần thử lại và không có hàng đợi nào để phát lại.

Bản thân phản hồi không hề bị ảnh hưởng. Nó được lưu trước khi yêu cầu được gửi đi và vẫn nằm trong bảng điều khiển của bạn dù endpoint có làm gì, nên bảng điều khiển vẫn là bản ghi đầy đủ ngay cả khi một lần gửi bị thất lạc.

Không có chữ ký số

Fillio không ký yêu cầu và không gửi khóa bí mật dùng chung, nên riêng phần thân không chứng minh được nó đến từ đâu. Nếu endpoint của bạn cần chắc chắn, hãy cho nó một địa chỉ chỉ mình bạn biết: một đường dẫn hoặc chuỗi truy vấn dài, khó đoán. Hãy coi mọi thứ đến từ nơi khác là không đáng tin.

Mỗi lần gửi mang ID sự kiện riêng, có trong cả header X-Fillio-Event-Id lẫn phần thân. Ghi lại những ID bạn đã xử lý là cách đơn giản nhất để endpoint của bạn an toàn khi bị gọi hai lần.