للمطوّرين — Webhooks وواجهةُ القراءة

للمطوّرين: Webhooks الفعاليّة وواجهةُ القراءة

آخر تحديث: ٢٦ سبتمبر ٢٠٢٦

إن كان لجهتك نظامٌ تعمل به – جدولُ بيانات، أو نظامُ تسجيل، أو برنامجُ مراسلة – فيمكن أن يصله كلُّ جديدٍ في فعاليّتك ساعةَ يحدث: مسجّلٌ جديد، أو بحثٌ رُفع، أو قرارُ تحكيم، أو مقعدٌ خلا لمن في قائمة الانتظار.

ولا يحتاج ذلك إلى حسابٍ خاصّ: يفتح المنظّم «ربطُ الفعاليّة بأنظمتك» من مربّع «للمنظّم» في صفحة فعاليّته، ويضع فيه رابطًا يأخذه من نظامه أو من خدمةٍ مثل Zapier. وما بعد هذه الفقرة تفصيلٌ للمبرمج الذي يُعدّ ذلك الرابط.

الربطُ بـZapier في ثلاث خطوات

في Zapier أنشئ Zap يبدأ بـWebhooks by Zapier → Catch Hook، وانسخ الرابطَ الذي يعطيك.
في صفحة فعاليّتك: «ربطُ الفعاليّة بأنظمتك» → ألصق الرابطَ → «احفظ الرابط» → «اختبار». يصل Zapier رسالةُ ping فيقرأ منها الحقول.
أكمل الـZap بما تريد: صفٌّ في جدول Google، رسالةٌ في Slack، جهةُ اتّصالٍ في نظامك. ثمّ شغّله.

الطريقةُ نفسُها مع Make وn8n وأيّ خادمٍ يقبل POST.

ما يُرسَل

الحدث `kind`	متى	ما في `data`
`registration.created`	سجّل عضوٌ في الفعاليّة	`registration`
`registration.accepted`	قبِل المنظّمُ تسجيلًا	`registration`
`registration.rejected`	رفض المنظّمُ تسجيلًا	`registration`
`registration.cancelled`	أُلغي تسجيلٌ (من صاحبه أو المنظّم)	`registration`
`waitlist.joined`	امتلأت المقاعدُ فانضمّ عضوٌ إلى قائمة الانتظار	`registration`
`waitlist.promoted`	فرغ مقعدٌ فحصل عليه أقدمُ المنتظرين	`registration`
`submission.created`	رُفع ملخّصٌ أو بحث	`submission`
`submission.decided`	تغيّرت حالةُ بحث (قبول/رفض/تعديل)	`submission`
`ping`	ضغط المنظّمُ «اختبار»	`message`

شكلُ الرسالة

طلبُ POST بجسم JSON بترميز UTF-8، ورؤوسٌ ثلاثة:

POST https://your-endpoint.example/hook
Content-Type: application/json
X-EventSheets-Event: registration.created
X-EventSheets-Delivery: 7c1e…-uuid
X-EventSheets-Signature: sha256=<hex>

{
  "id": "7c1e0a5e-…",
  "kind": "registration.created",
  "occurred_at": "2026-11-07T09:30:12+00:00",
  "event": { "id": 1461, "title": "…", "title_en": "…", "url": "https://eventsheets.com/ar/events/details?event_id=1461" },
  "data": {
    "registration": {
      "registration_id": 5120,
      "type": "participant",            // attendee | participant
      "status": "accepted",             // pending | accepted | rejected | waitlisted
      "registered_at": "2026-11-07 09:30:12",
      "member": { "id": 193, "name": "…", "email": "…", "country": "…" }
    }
  }
}

وفي أحداث البحوث يحلّ submission محلّ registration: submission_id، title، kind (abstract أو full_paper)، status (pending | accepted | rejected | revise)، submitted_at، وauthor بالحقول نفسِها. الملفُّ نفسُه لا يُرسَل؛ يُحمَّل من صفحة الفعاليّة بصلاحيّة المنظّم.

التحقّقُ من التوقيع

لكلّ رابطٍ مفتاحٌ سرّيّ يظهر للمنظّم في الشاشة نفسِها. التوقيعُ هو HMAC‑SHA256 لجسم الطلب بالبايتات كما وصلت بذلك المفتاح، بصيغة hex. تحقّق منه قبل أن تصدّق الرسالة، فالرابطُ نفسُه قد يعرفه غيرُك:

// PHP
$body = file_get_contents('php://input');
$sig  = $_SERVER['HTTP_X_EVENTSHEETS_SIGNATURE'] ?? '';
$ok   = hash_equals('sha256=' . hash_hmac('sha256', $body, $secret), $sig);

// Node
const ok = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex') === req.get('X-EventSheets-Signature');

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

لا إعادةَ إرسال. كلُّ حدثٍ يُرسَل مرّةً واحدة، وينتظر الموقعُ ردًّا حتّى ستّ ثوانٍ. ردٌّ من عائلة 2xx يعني «وصل»؛ غيرُه يُسجَّل إخفاقًا في سجلّ الرابط الذي يراه المنظّم.
عشرون إخفاقًا متتاليًا توقف الرابطَ تلقائيًّا، ويقول السجلُّ ذلك. يُعاد تشغيله بزرّ.
الرابطُ https فقط، إلى خادمٍ عامٍّ له اسمٌ يُحلّ؛ العناوينُ الخاصّة والـIP المجرّدة تُرفض.
يُرسَل الحدثُ بعد أن يُردَّ على الزائر، فلا يبطئ التسجيلَ خادمٌ بطيء عندك.
لكلّ فعاليّة ثلاثةُ روابطَ على الأكثر، ولكلّ رابطٍ أن يختار الأحداثَ التي يريدها.
ردّ X-EventSheets-Delivery فريدٌ لكلّ إرسال؛ استعمله لتجاهل التكرار إن كنتَ تخزّن.

واجهةُ القراءة

الفعاليّاتُ المنشورة تُقرأ بلا مفتاح من GET /api/event (قائمة) وGET /api/event/{id} (فعاليّة واحدة)، JSON، بالحقول التي تظهر في الصفحة العامّة. غيرُ المنشور لا يُرجَع. وصفحةُ كلّ فعاليّة تحمل بياناتٍ منظّمة (JSON‑LD من نوع Event) وملفَّ .ics، وهما أبسطُ طريقٍ لقارئٍ آليّ.

أخبرنا

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