كيف تعمل الـ Webhooks في VeloCMS؟
الـ Webhooks هي إشعارات HTTP POST صادرة يرسلها VeloCMS عند وقوع الأحداث، وتُوقَّع بـ HMAC-SHA256 ليتحقق خادمك من هوية المُرسِل.
الـ webhook في VeloCMS هو طلب HTTP POST صادر يُرسَل إلى رابط تُسجّله أنت كلما وقع حدث محدد في مدونتك — كنشر مقال جديد، أو انضمام مشترك جديد، أو اكتمال طلب شراء. جسم الطلب كائن JSON، ويتضمن الطلب رأس توقيع HMAC-SHA256 حتى يتمكن الخادم المستقبِل من التحقق من أن الطلب صادر فعلًا من VeloCMS.
كيف تبدو بيانات JSON الخاصة بـ webhook؟
تتبع كل حمولة webhook بنية غلاف موحّدة: id (معرّف تسليم فريد)، وevent (نوع الحدث مثل 'post.published')، وversion (وهو حاليًا 1)، وcreated (طابع زمني Unix بالثواني)، وtenant (الـ slug الخاص بمدوّنتك)، وكائن data يحتوي على الحقول الخاصة بالحدث. ففي حدث post.published يضم كائن data الحقول post_id وtitle وslug وstatus وpublished_at وexcerpt وtags (مصفوفة بأسماء الوسوم) وauthor_name. وفي حدث member.subscribed يضم member_id وemail وtier وsubscribed_at. ويُنشر المخطط المقروء آليًا لكل حدث على شكل مستند AsyncAPI 3.0 على /api/v1/asyncapi في مدوّنتك.
كيف أتحقق من أن webhook صادر من VeloCMS؟
يحمل كل طلب webhook ثلاث ترويسات يحتاج إليها خادمك: X-VeloCMS-Event (نوع الحدث)، وX-VeloCMS-Timestamp (الطابع الزمني Unix المستخدم في التوقيع)، وX-VeloCMS-Signature بالصيغة v1=<hex digest>. والملخّص هو HMAC-SHA256 للسلسلة v1:{timestamp}:{raw request body}، محسوبًا بالمفتاح السري لنقطة نهاية webhook الخاصة بك — وتوقيع الطابع الزمني مع الجسم يتيح لك رفض الطلبات القديمة المُعاد إرسالها. وللتحقق: اقرأ ترويسة الطابع الزمني، وأعد بناء السلسلة v1:{timestamp}:{body} من جسم الطلب الخام كما وصل تمامًا، واحسب HMAC-SHA256 بمفتاحك السري، وقارن النتيجة بالملخّص في ترويسة التوقيع. فإن تطابقا فالطلب أصيل، وإن لم يتطابقا فارفضه. يُعرض المفتاح السري مرة واحدة في نافذة حوارية عند إنشاء نقطة النهاية في لوحة التحكم ← الإعدادات ← متقدم ← ويب هوك — فاحفظه بأمان لأن VeloCMS لا يستطيع عرضه مجددًا. وإن فقدته فاحذف نقطة النهاية وأنشئ أخرى جديدة لتحصل على مفتاح سري جديد.
ما حالة HTTP التي ينبغي أن يُعيدها الخادم؟
أعِد أي حالة 2xx (200 أو 201 أو 204) في غضون 10 ثوانٍ لتأكيد الاستلام. يعتبر VeloCMS التسليم ناجحًا فور استلامه أي استجابة 2xx — فهو لا يحلّل جسم استجابتك. وإذا استغرقت معالجتك أكثر من 10 ثوانٍ، فالنهج الصحيح هو تأكيد الاستلام فورًا بـ 200 OK ثم معالجة الحمولة بصورة غير متزامنة في الخلفية. وأي استجابة غير 2xx — سواء 4xx أو 5xx — أو انتهاء مهلة الاتصال يُشغّل منطق إعادة المحاولة في VeloCMS وفق جدول متباعد: خمس دقائق، ثم ثلاثون دقيقة، ثم ساعتان، ثم ست ساعات، ثم أربع وعشرون ساعة (ست محاولات إجمالًا بما فيها المحاولة الأصلية). وبعد فشل المحاولة الأخيرة يُوسَم التسليم بأنه فاشل، ويُعطَّل الطرف المستقبِل، ويرسل VeloCMS بريدًا إلى مالك الموقع؛ وتعيد تفعيل نقطة النهاية من لوحة الـ webhooks حين يعود خادمك سليمًا. وثمة تنبيه واحد: لا تُتَّبع إعادات التوجيه أبدًا، لذا تُعدّ استجابة 3xx فشلًا — سجّل عنوان نقطة النهاية النهائي مباشرةً.
هل يمكنني اختبار عمليات تسليم webhook دون نشر مقال حقيقي؟
نعم. في لوحة التحكم ← الإعدادات ← متقدم ← ويب هوك، لكل نقطة نهاية مسجَّلة زر «إرسال اختبار» (أيقونة البرق). بالنقر عليه، يُرسَل فورًا حدث test.ping إلى رابط نقطة النهاية، مع رأس X-VeloCMS-Signature نفسه المستخدم في حدث حقيقي. يتيح لك ذلك التحقق من فحص التوقيع في خادمك ومن معالجة الاستجابة دون الحاجة إلى إنشاء محتوى فعلي. تحمل البيانات معرّف الـ webhook ورسالة قصيرة، ونوع الحدث هو test.ping، فيستطيع خادمك التعرّف عليه وتخطي معالجته.
معرّف التسليم في غلاف webhook (حقل 'id') ثابت عبر عمليات إعادة المحاولة — فالحدث نفسه يحمل دائمًا معرّف التسليم نفسه. استخدمه لمنع تكرار المعالجة في الخادم المستقبِل: احفظ معرّفات التسليم التي استلمتها وتخطَّ المعالجة إذا سبق أن تعاملت مع المعرّف نفسه. وهذا يمنع تكرار الآثار الجانبية إذا أعاد VeloCMS تسليم حدث عالجه خادمك بالفعل.