حمولات Webhook

يُرسل كل طلب webhook من NueForm حمولة JSON في جسم الطلب. توثق هذه الصفحة مخطط الحمولة الكامل لكل نوع حدث.

الهيكل المشترك

تشترك جميع حمولات webhook في هذه الحقول ذات المستوى الأعلى:

حمولة form.submitted

هذه هي الحمولة المُرسلة عندما يُرسل المستجيب استجابة نموذج كاملة.

مثال كامل

{
  "event": "form.submitted",
  "formId": "507f1f77bcf86cd799439011",
  "formTitle": "Customer Feedback Survey",
  "responseId": "507f1f77bcf86cd799439022",
  "answers": [
    {
      "questionId": "507f1f77bcf86cd799439033",
      "value": "Jane Doe",
      "label": "What's your name?",
      "type": "short_text"
    },
    {
      "questionId": "507f1f77bcf86cd799439044",
      "value": "jane@example.com",
      "label": "What's your email address?",
      "type": "email"
    },
    {
      "questionId": "507f1f77bcf86cd799439055",
      "value": 4,
      "label": "How would you rate your experience?",
      "type": "rating"
    },
    {
      "questionId": "507f1f77bcf86cd799439066",
      "value": "The onboarding flow was smooth and intuitive.",
      "label": "What did you like most?",
      "type": "long_text"
    },
    {
      "questionId": "507f1f77bcf86cd799439077",
      "value": ["c3a1e5f2-8b4d-4f6a-9e21-7d0b3c8a5f14", "9b7e2d41-5c3f-4a8e-b6d0-1f2a4c6e8b93"],
      "label": "Which features do you use?",
      "type": "multiple_choice"
    },
    {
      "questionId": "507f1f77bcf86cd799439088",
      "value": true,
      "label": "Would you recommend us?",
      "type": "yes_no"
    }
  ],
  "respondent": {
    "id": "507f1f77bcf86cd799439016",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "auth_method": "sso"
  },
  "submittedAt": "2025-03-15T14:32:07.123Z"
}

مرجع الحقول

حقول المستوى الأعلى

event --- string

دائماً "form.submitted" لهذا النوع من الأحداث.

formId --- string

معرّف MongoDB ObjectId للنموذج. سلسلة سداسية عشرية من ٢٤ حرفاً.

formTitle --- string

العنوان المقروء للنموذج وقت إطلاق webhook. لاحظ أنه إذا أعدت تسمية النموذج لاحقاً، ستظل webhooks المُسلّمة سابقاً تحتوي على العنوان القديم.

responseId --- string

معرّف MongoDB ObjectId للاستجابة المخزنة. يمكنك استخدامه لجلب الاستجابة الكاملة عبر واجهة الاستجابات API أو كمفتاح تجنب تكرار لإزالة تكرار تسليمات webhook.

submittedAt --- string

طابع وقت ISO 8601 يشير إلى وقت إرسال webhook. يُنشأ وقت الإرسال وسيكون قريباً جداً من (لكن ليس بالضرورة مطابقاً لـ) حقل submittedAt في قاعدة البيانات.

respondent --- object أو null

هوية المستخدم المسجّل الذي أرسل الاستجابة، تُكشف فقط عندما يشترط النموذج تسجيل الدخول (requireLogin: true). تكون null لجميع الإرسالات المجهولة. انظر هوية المستجيب أدناه للحصول على المخطط الكامل والسلوك.

كائنات الإجابات

يمثل كل عنصر في مصفوفة answers إجابة سؤال واحد:

أما إجابات المكالمات الهاتفية فتحمل questionId وvalue، ومعهما valueLabels للقائمة المأخوذة من متغيّر. وقد تحمل إجابات الويب أيضًا viewedAt وansweredAt: وقت عرض السؤال ووقت الإجابة عنه، كطوابع زمنية بتنسيق ISO 8601 من جهاز المستجيب. وقد تُضاف حقول أخرى مع الوقت، لذا تجاهل ما لا تستخدمه منها.

وتبدو إجابة الويب عن قائمة محمّلة من متغيّر هكذا:

{
  "questionId": "507f1f77bcf86cd799439099",
  "value": "siamese",
  "label": "Which breed is your cat?",
  "type": "dropdown",
  "valueLabels": { "siamese": "Siamese" }
}

أما الإجابة نفسها إذا أُعطيت في مكالمة هاتفية فتصل دون label وtype.

قيم الإجابات حسب نوع السؤال

يختلف حقل value في كل كائن إجابة حسب نوع السؤال. إليك التنسيق لكل نوع:

مدخلات النص

أسئلة الاختيار

تحمل value معرّفات الخيارات لا تسمياتها: أي id كل خيار مختار ضمن choices الخاصة بالسؤال. والمعرّفات التي يُنشئها المنشئ هي بصيغة UUID. وتقبل واجهة API وخادم MCP أيضًا خيارًا بلا id، مثل { "label": "Search engine" }؛ وعندها تحمل value في إجابة الويب قيمة label لذلك الخيار بدلًا من المعرّف. يرسل multiple_choice وdropdown سلسلة نصية واحدة، أو مصفوفة سلاسل نصية عندما يكون allowMultiple بقيمة true. وخيارات الصور (layout: "blocks") هي أيضًا أسئلة multiple_choice.

إذا اختار المستجيب أخرى، يكون العنصر __other__: متبوعًا بالنص الذي كتبه، كما في المثال أعلاه. أما المكالمة الهاتفية فتحفظ إجابة «أخرى» بكلمات المتصل نفسه، دون البادئة.

أسئلة التقييم

التاريخ والوقت

يطابق تنسيق سلسلة التاريخ خاصية dateFormat المُعدّة على السؤال (الافتراضي YYYY-MM-DD).

القانوني والبيانات

الترتيب

تحمل المصفوفة معرّفات الخيارات بالترتيب الذي اختاره المستجيب، من الأول إلى الأخير؛ وفي إجابة الويب، يظهر الخيار المحفوظ بلا id بقيمة label الخاصة به بدلًا من المعرّف. اربط المعرّفات بتسمياتها كما في أسئلة الاختيار.

المصفوفة

في المصفوفة ذات الصفوف والأعمدة الثابتة، يربط الكائن تسمية كل صف بتسمية العمود المُحدد. وعندما تأتي صفوفها أو أعمدتها من متغيّر، يربط قيم الصفوف بـقيم الأعمدة، وتكون التسميات التي رآها المستجيب في valueLabels الخاصة بالإجابة، تحت المفاتيح row:<القيمة> وcolumn:<القيمة>.

رفع الملفات

القيمة هي عنوان URL للملف المرفوع في تخزين NueForm.

التوقيع والرسم

كلاهما يعيد URI بيانات PNG مشفرة بـ base64 للصورة الملتقطة.

التسجيل

القيمة هي عنوان URL لملف التسجيل المرفوع.

الأسئلة المركبة

تُنتج أنواع الأسئلة المركبة (contact_info وaddress وquestion_group وmulti_question_page) عنصر إجابة واحدًا تحت questionId الخاص بالسؤال المركب نفسه. وتكون value فيه كائنًا مفاتيحه معرّفات الحقول الفرعية. تستخدم معلومات الاتصال والعنوان معرّفات مدمجة مثل first_name وzip_code، بينما تستخدم مجموعة الأسئلة أو صفحة الأسئلة المتعددة معرّف كل سؤال بداخلها. وتتبع قيمة كل حقل فرعي تنسيق نوع سؤاله. وتحمل إجابات الويب أيضًا subLabels، التي تربط معرّف كل حقل فرعي بتسميته.

مثلاً، يُنتج سؤال contact_info:

{
  "questionId": "507f1f77bcf86cd7994390aa",
  "value": {
    "first_name": "Jane",
    "last_name": "Doe",
    "phone_number": "+1 555-0100",
    "email": "jane@example.com",
    "company": "Acme Inc."
  },
  "label": "How can we reach you?",
  "type": "contact_info",
  "subLabels": {
    "first_name": "First Name",
    "last_name": "Last Name",
    "phone_number": "Phone Number",
    "email": "Email",
    "company": "Company"
  }
}

أما الإجابة نفسها إذا أُعطيت في مكالمة هاتفية فلها value نفسها، لكنها تصل دون label وtype وsubLabels.

هوية المستجيب

عند تكوين نموذج بـ requireLogin: true، يُربط كل إرسال مقبول بمستخدم مسجّل الدخول. تكشف حمولات webhook عن هذه الهوية لأصحاب النماذج عبر حقل respondent. أما لجميع الإرسالات الأخرى فيكون الحقل null.

المخطط

{
  "respondent": {
    "id": "507f1f77bcf86cd799439016",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "auth_method": "sso"
  }
}

متى يتم تعبئة respondent

تتم تعبئة respondent فقط عندما:

1. يكون لدى النموذج requireLogin مضبوطاً على true، و
2. سجّل المُرسِل دخوله لأن النموذج اشترط ذلك قبل الإرسال.

عندما يكون requireSsoLogin أيضاً true، يمكن فقط للمستخدمين الأعضاء في فريق النموذج عبر SSO الوصول إلى خطوة الإرسال، لذا فإن كل respondent مُعبَّأ سيكون auth_method: "sso".

متى يكون respondent بقيمة null

الحقل موجود دائماً في JSON من أجل تحليل تنبؤي للمستهلك، وهو null كلما تحققت أيٌّ من الحالات التالية:

• لم يشترط النموذج تسجيل الدخول (requireLogin كان false).
• كان المُرسِل مجهولاً.
• حُفظت الاستجابة عبر تدفق الموافقة بعد الإرسال (مطالبة "اطلب هذه الاستجابة"). الاستجابات المحفوظة بالموافقة لا تظهر أبداً في حمولات webhook بهوية مرفقة — إنها تُخزَّن فقط في عرض "استجاباتي" للمستخدم ولا تُكشف لمستقبلي webhook.

نتائج الاختبار

للنماذج التي تعمل في وضع اختبار (knowledge_quiz أو lead_qualification أو match_quiz)، تتضمن الاستجابة المخزنة كائن quizResults. بينما لا يُضمّن هذا الكائن مباشرة في حمولة webhook، يمكنك استرجاعه عبر واجهة الاستجابات API باستخدام responseId من webhook.

يحتوي كائن quizResults على الهيكل التالي:

{
  "formMode": "knowledge_quiz",
  "score": 7,
  "correctAnswers": 7,
  "totalScorableQuestions": 10,
  "maxScore": 10,
  "matchedEndingId": "507f1f77bcf86cd799439099"
}

البيانات الوصفية

قد تتضمن الاستجابة المخزنة أيضاً كائن metadata يحتوي على حقول مخفية مُمررة عبر معلمات URL. هذا متاح عبر واجهة الاستجابات API لكنه غير مُضمّن في حمولة webhook.

{
  "hiddenFields": {
    "utm_source": "google",
    "utm_campaign": "spring_sale",
    "user_id": "ext_12345"
  }
}

للوصول إلى البيانات الوصفية لاستجابة مُسلّمة عبر webhook، اجلبها باستخدام responseId:

curl https://app.nueform.io/api/v1/forms/FORM_ID/responses/RESPONSE_ID \
  -H "Authorization: Bearer nf_your_api_key"

ترويسات HTTP

يتضمن كل طلب webhook هذه الترويسات HTTP:

راجع التحقق لكيفية التحقق من صحة التوقيع.

حجم الحمولة

حمولات webhook عادة صغيرة (أقل من ١٠ كيلوبايت). يعتمد الحجم بشكل أساسي على عدد الأسئلة وطول إجابات النص. تحتوي إجابات رفع الملفات على عناوين URL (وليس محتويات الملفات)، لذا لا تزيد حجم الحمولة بشكل كبير.

الخطوات التالية

• التحقق --- تحقق من صحة توقيعات webhook
• الاختبار --- اختبر حمولات webhook محلياً
• الأحداث --- أنواع الأحداث وضمانات التسليم