حمولات Webhook | NueForm Docs

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

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

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

الحقل	النوع	الوصف
`event`	`string`	نوع الحدث (مثل `form.submitted`)
`formId`	`string`	المعرّف الفريد للنموذج
`formTitle`	`string`	عنوان النموذج وقت الإرسال
`responseId`	`string`	المعرّف الفريد للاستجابة
`answers`	`array`	مصفوفة كائنات الإجابات
`submittedAt`	`string`	طابع وقت ISO 8601 لوقت إرسال الحدث

حمولة `form.submitted`

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

مثال كامل

json

{
  "event": "form.submitted",
  "formId": "507f1f77bcf86cd799439011",
  "formTitle": "Customer Feedback Survey",
  "responseId": "507f1f77bcf86cd799439022",
  "answers": [
    {
      "questionId": "507f1f77bcf86cd799439033",
      "value": "Jane Doe"
    },
    {
      "questionId": "507f1f77bcf86cd799439044",
      "value": "jane@example.com"
    },
    {
      "questionId": "507f1f77bcf86cd799439055",
      "value": 4
    },
    {
      "questionId": "507f1f77bcf86cd799439066",
      "value": "The onboarding flow was smooth and intuitive."
    },
    {
      "questionId": "507f1f77bcf86cd799439077",
      "value": ["Feature A", "Feature C"]
    },
    {
      "questionId": "507f1f77bcf86cd799439088",
      "value": true
    }
  ],
  "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 في قاعدة البيانات.

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

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

الحقل	النوع	الوصف
`questionId`	`string`	معرّف MongoDB ObjectId للسؤال
`value`	`any`	إجابة المستجيب (يختلف التنسيق حسب نوع السؤال)

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

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

مدخلات النص

نوع السؤال	نوع القيمة	مثال
`short_text`	`string`	`"Jane Doe"`
`long_text`	`string`	`"I really enjoyed the product..."`
`email`	`string`	`"jane@example.com"`
`phone`	`string`	`"+1 (555) 123-4567"`
`number`	`number`	`42`
`url`	`string`	`"https://example.com"`

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

نوع السؤال	نوع القيمة	مثال
`multiple_choice` (مفرد)	`string`	`"Option A"`
`multiple_choice` (متعدد)	`array<string>`	`["Option A", "Option C"]`
`dropdown`	`string`	`"United States"`
`yes_no`	`boolean`	`true`
`picture_choice` (مفرد)	`string`	`"choice_id_abc123"`
`picture_choice` (متعدد)	`array<string>`	`["choice_id_abc123", "choice_id_def456"]`

لأسئلة multiple_choice، تكون القيمة سلسلة نصية واحدة عندما يكون allowMultiple بقيمة false، ومصفوفة سلاسل نصية عندما يكون allowMultiple بقيمة true. إذا اختار المستجيب خيار "أخرى"، ستحتوي المصفوفة على إدخال النص الحر كسلسلة نصية.

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

نوع السؤال	نوع القيمة	مثال	النطاق
`rating`	`number`	`4`	١ إلى `steps` (افتراضي ٥)
`opinion_scale`	`number`	`7`	`min` إلى `max`
`nps`	`number`	`9`	٠ إلى ١٠

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

نوع السؤال	نوع القيمة	مثال
`date`	`string`	`"2025-03-15"`

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

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

نوع السؤال	نوع القيمة	مثال
`legal`	`boolean`	`true`
`statement`	`string`	`""` (فارغ دائماً --- البيانات لا تجمع بيانات)

الترتيب

نوع السؤال	نوع القيمة	مثال
`ranking`	`array<string>`	`["Speed", "Price", "Quality"]`

تعكس المصفوفة الترتيب الذي اختاره المستجيب، من الأول إلى الأخير.

المصفوفة

نوع السؤال	نوع القيمة	مثال
`matrix`	`object`	`{ "Speed": "Satisfied", "Price": "Neutral" }`

يربط الكائن تسميات الصفوف بتسمية العمود المُحدد لكل صف.

رفع الملفات

نوع السؤال	نوع القيمة	مثال
`file_upload`	`string`	`"https://storage.nueform.com/uploads/abc123.pdf"`

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

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

نوع السؤال	نوع القيمة	مثال
`signature`	`string`	`"data:image/png;base64,iVBOR..."`
`drawing`	`string`	`"data:image/png;base64,iVBOR..."`

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

التسجيل

نوع السؤال	نوع القيمة	مثال
`recording`	`string`	`"https://storage.nueform.com/recordings/abc123.webm"`

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

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

تُنتج أنواع الأسئلة المركبة (contact_info و address و question_group و multi_question_page) عناصر إجابة متعددة في مصفوفة answers --- واحد لكل حقل فرعي. يستخدم كل إجابة حقل فرعي questionId الخاص به.

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

json

[
  { "questionId": "first_name", "value": "Jane" },
  { "questionId": "last_name", "value": "Doe" },
  { "questionId": "email", "value": "jane@example.com" },
  { "questionId": "phone_number", "value": "+1 555-0100" },
  { "questionId": "company", "value": "Acme Inc." }
]

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

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

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

json

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

الحقل	النوع	الوصف
`formMode`	`string`	وضع الاختبار: `knowledge_quiz` أو `lead_qualification` أو `match_quiz`
`score`	`number`	مجموع نقاط المستجيب
`correctAnswers`	`number`	عدد الأسئلة المُجابة بشكل صحيح (اختبار المعرفة فقط؛ `0` للأوضاع الأخرى)
`totalScorableQuestions`	`number`	إجمالي عدد الأسئلة التي تساهم في النتيجة
`maxScore`	`number`	أقصى نتيجة ممكنة
`matchedEndingId`	`string` أو `undefined`	معرّف شاشة النهاية المعروضة للمستجيب بناءً على نتيجته
`endingTallies`	`object` أو `undefined`	اختبار المطابقة فقط: يربط كل معرّف شاشة نهاية بعدد التصويتات

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

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

json

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

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

bash

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

ترويسات HTTP

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

الترويسة	القيمة
`Content-Type`	`application/json`
`X-NueForm-Signature`	ملخص HMAC-SHA256 سداسي عشري لجسم الطلب الخام

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

حجم الحمولة

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

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

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