Webhooks

تفعيل Webhook

افتح النموذج، وانتقل إلى تبويب الإعدادات وفعّل Webhook. الصق العنوان الذي يجب أن يستقبل الردود؛ يحفظه Fillio بعد لحظة من توقفك عن الكتابة ويؤكد ذلك على الشاشة. ولكل نموذج عنوان واحد، وإيقاف المفتاح يمسحه.

يجب أن يكون العنوان HTTPS

لا يستدعي Fillio إلا العناوين التي تبدأ بـ https://. أما عنوان http:// فيقبله حقل الإعدادات لكنه لا يُستدعى أبدًا، فيبدو عنوان webhook محفوظًا بينما لا يُسلّم شيئًا في الواقع.

وتُرفض كذلك العناوين التي تشير إلى داخل شبكة خاصة: أي مضيف على 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

تحمل كل مدخلة أربع خصائص، ويحمل السؤال ذو الخيارات خاصية خامسة.

لا تصل إلا الأسئلة المُجاب عنها

السؤال الذي تركه المستجيب دون إجابة يغيب عن المصفوفة بدل أن يُرسل بقيمة فارغة، والسؤال الذي أخفاه المنطق الشرطي لا يظهر إطلاقًا. فابحث عن كل إجابة بمفتاحها بدل الاعتماد على الموضع أو على عدد ثابت من المدخلات.

إجابات الاختيار تحمل معرّفات لا تسميات

إجابة القائمة المنسدلة أو الاختيار من متعدد هي معرّف الخيار المحدد، وإجابة مربعات التحديد أو الاختيار المتعدد أو الترتيب هي مصفوفة من معرّفات الخيارات. حلّها مقابل قائمة options في المدخلة نفسها. وتحتفظ إجابة الترتيب بالترتيب الذي وضع المستجيب العناصر فيه.

خيار أخرى

حين يكتب المستجيب في مربع أخرى، لا تكون القيمة معرّف خيار بل النص __OTHER__: متبوعًا بما كتبه. أزل هذه البادئة لقراءة الإجابة.

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

الملفات والتواقيع

إجابة رفع الملف هي رابط تنزيل للملف في تخزين Fillio. وإجابة التوقيع هي عنوان بيانات PNG بترميز base64، يمكنك حفظه أو عرضه مباشرة.

أنواع الحقول

النوع اسم عام ثابت، فأي تغيير داخل Fillio لا يصل إلى تكاملك. وأي شيء يعجز Fillio عن مطابقته يصل بالنوع INPUT_TEXT.

إذا لم تستجب نقطة النهاية

ينتظر Fillio عشر ثوانٍ. وانتهاء المهلة أو خطأ الاتصال أو أي حالة خارج النطاق 2xx يُعدّ تسليمًا فاشلًا، وهذه هي النهاية: لا إعادة محاولة ولا طابور يُعاد التشغيل منه.

أما الرد نفسه فلا يتأثر إطلاقًا. فهو يُخزَّن قبل إرسال الطلب ويبقى في لوحة تحكمك مهما فعلت نقطة النهاية، لتظل اللوحة سجلًا كاملًا حتى لو ضاع تسليم.

لا يوجد توقيع

لا يوقّع Fillio الطلب ولا يرسل أي سر مشترك، فالجسم وحده لا يثبت مصدره. وإن كان لا بد أن تتيقن نقطة نهايتك، فامنحها عنوانًا تعرفه أنت وحدك: مسارًا أو سلسلة استعلام طويلة يصعب تخمينها. وعامل أي شيء يصل إلى مكان آخر على أنه غير موثوق.

يحمل كل تسليم معرّف حدث خاصًا به، في ترويسة X-Fillio-Event-Id وفي الجسم معًا. وتسجيل ما عالجته من هذه المعرّفات هو أبسط طريقة لجعل نقطة نهايتك آمنة عند استدعائها مرتين.