وب‌هوک‌ها

روشن کردن وب‌هوک

فرم را باز کنید، به تب «تنظیمات» بروید و «وب‌هوک» را روشن کنید. نشانی‌ای را که باید پاسخ‌ها را دریافت کند بچسبانید؛ Fillio کمی بعد از آنکه دست از تایپ برداشتید آن را ذخیره می‌کند و روی صفحه تأییدش می‌کند. هر فرم یک نشانی دارد و خاموش کردن دوبارهٔ کلید آن را پاک می‌کند.

نشانی باید HTTPS باشد

Fillio فقط نشانی‌هایی را صدا می‌زند که با https:// شروع می‌شوند. نشانی http:// در فیلد تنظیمات پذیرفته می‌شود اما هرگز صدا زده نمی‌شود، پس وب‌هوکی که به نظر ذخیره‌شده می‌آید در سکوت هیچ‌چیز تحویل نمی‌دهد.

نشانی‌هایی که به درون یک شبکهٔ خصوصی اشاره می‌کنند هم رد می‌شوند: هر میزبانی روی 10.x، 127.x، 169.254.x، 172.16-31.x یا 192.168.x، هر نشانی IPv6، و هر نامی که localhost باشد یا به ‎.local یا ‎.internal ختم شود. اندپوینت شما باید از اینترنت عمومی قابل دسترسی باشد.

درخواست

یک POST با بدنهٔ JSON. چهار هدر همراهش می‌آید.

بستهٔ ارسالی

یک پوشش که رویداد را توصیف می‌کند، و یک شیء 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 خودش پیدا کنید، نه با تکیه بر جایگاه یا بر تعداد ثابتی از ورودی‌ها.

پاسخ‌های گزینه‌ای شناسه دارند، نه برچسب

پاسخ یک پرسش کشویی یا چندگزینه‌ای، شناسهٔ گزینهٔ انتخاب‌شده است، و پاسخ چک‌باکس، چندانتخابی یا رتبه‌بندی، آرایه‌ای از شناسهٔ گزینه‌هاست. آن‌ها را با فهرست options در همان ورودی تطبیق بدهید. پاسخ رتبه‌بندی ترتیبی را که پاسخ‌دهنده چیده نگه می‌دارد.

گزینهٔ «سایر»

وقتی پاسخ‌دهنده در کادر «سایر» چیزی می‌نویسد، مقدار دیگر شناسهٔ گزینه نیست بلکه متن ‎__OTHER__:‎ است و پس از آن چیزی که نوشته. برای خواندن پاسخ، این پیشوند را جدا کنید.

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

فایل‌ها و امضاها

پاسخ بارگذاری فایل، لینک دانلود آن فایل در فضای ذخیره‌سازی Fillio است. پاسخ امضا یک data URL از نوع PNG در قالب base64 است که می‌توانید مستقیم ذخیره یا نمایشش دهید.

نوع فیلدها

نوع، یک نام عمومی و پایدار است، پس تغییری در دل Fillio هرگز به یکپارچه‌سازی شما نمی‌رسد. هر چیزی که Fillio نتواند نگاشت کند به‌صورت INPUT_TEXT می‌رسد.

اگر اندپوینت شما جواب ندهد

Fillio ده ثانیه صبر می‌کند. تمام شدن مهلت، خطای اتصال یا هر وضعیتی بیرون از بازهٔ 2xx یعنی تحویل ناموفق، و کار همان‌جا تمام است: نه تلاش دوباره‌ای در کار است و نه صفی که بشود از آن بازپخش کرد.

خودِ پاسخ هرگز آسیب نمی‌بیند. پیش از فرستادن درخواست ذخیره می‌شود و هر بلایی که سر اندپوینت شما بیاید در داشبورد باقی می‌ماند، پس حتی اگر تحویلی از دست برود، داشبورد همچنان سند کامل ماجراست.

امضایی در کار نیست

Fillio درخواست را امضا نمی‌کند و هیچ کلید مشترکی نمی‌فرستد، پس بدنه به‌تنهایی ثابت نمی‌کند از کجا آمده است. اگر اندپوینت شما باید مطمئن باشد، نشانی‌ای به آن بدهید که فقط خودتان می‌دانید: یک مسیر یا کوئری بلند و حدس‌ناپذیر. هر چیزی را که جای دیگری می‌رسد نامعتبر بدانید.

هر تحویل شناسهٔ رویداد خودش را دارد، هم در هدر X-Fillio-Event-Id و هم در بدنه. ساده‌ترین راه برای اینکه صدا زدن دوبارهٔ اندپوینت‌تان بی‌خطر باشد، ثبت کردن شناسه‌هایی است که قبلاً پردازش کرده‌اید.