ما هو الـ webhook؟
الـ webhook طلب HTTP ترسله خدمة ما إلى عنوان تسجّله عندما يحدث شيء — تسوية دفعة، أو تسليم رسالة، أو انتهاء بناء — فيتفاعل نظامك مع الأحداث بدلاً من الاستطلاع المتكرر. اختباره يعني التقاط ما يُرسَل فعلياً (الأسلوب والترويسات والجسم)، وفحص إعادة المحاولة والترتيب، والتحقق من التوقيع الذي يثبت أن النداء جاء من المرسِل.
ملاحظة أمنية: نقطة نهاية الـ webhook عنوان عام يمكن لأي شخص الإرسال إليه. تحقق من توقيع المرسِل (عادةً HMAC على الجسم الخام) بمقارنة ثابتة الزمن، وارفض الطوابع الزمنية القديمة، وتعامل مع الحمولة كمدخل غير موثوق.
اقرأ الدليل: ما هو اختبار API؟ وكيف تختبر REST API
كيفية استخدام مختبِر Webhook
- اضغط «إنشاء رابط التقاط» وانسخ العنوان.
- اضبطه وجهةً لطلبات webhook لدى مزوّدك (أو أرسل طلباً باستخدام cURL / الأمر النموذجي).
- انتظر لحظة — تظهر عمليات التسليم في القائمة؛ انقر على إحداها لفحصها.
- استخدم تبويب «إعادة الإرسال» (Replay) لإنشاء أمر cURL يعيد إرسال التسليم إلى خادمك.
- احذف نقطة النهاية عند الانتهاء (أو دع صلاحيتها تنتهي).
- مزوّد الـ webhook مثل Stripe
- خدمة الالتقاط عنوان الالتقاط + API
- هذه الصفحة متصفحك
- أنت وخادمك الطرفية والمعالج
- 1 من هذه الصفحة إلى خدمة الالتقاط: إنشاء رابط التقاط
POST /api/v1/webhooks - 2 من خدمة الالتقاط إلى هذه الصفحة: عنوان الالتقاط ورمز خاص ردّ يُحفظ في جلسة المتصفح فيبقى بعد تحديث الصفحة
https://www.mutqansoft.sa/hooks/3f9c… - 3 من أنت وخادمك إلى مزوّد الـ webhook: اضبطه وجهةً لطلبات webhook أو أرسل طلباً بنفسك باستخدام cURL
- 4 من مزوّد الـ webhook إلى خدمة الالتقاط: يقع حدث فيرسله المزوّد بطلب POST ترويسات منها التوقيع، وجسم JSON
Stripe-Signature: t=1725184801,v1=… - 5 من خدمة الالتقاط إلى مزوّد الـ webhook:
200 OKردّ مع جسم JSON صغير، وهو ما يلبّي معظم فحوصات التسليم - 6 من هذه الصفحة إلى خدمة الالتقاط: تستعلم عن عمليات التسليم الجديدة كل 3 ثوانٍ ما دام التبويب مرئياً، مع الرمز
GET /api/v1/webhooks/:id/requests - 7 من خدمة الالتقاط إلى هذه الصفحة: تظهر عمليات التسليم الجديدة في القائمة ردّ الطريقة والمسار والترويسات (بيانات الاعتماد بالقيمة [redacted]) والجسم والحجم والوقت
- 8 من هذه الصفحة إلى أنت وخادمك: تبويب إعادة الإرسال ينشئ أمر cURL مع الاحتفاظ بترويسات المزوّد والتوقيع
- 9 أنت وخادمك داخليًا: تشغّله أنت على خادمك أعد القيمة الحقيقية لأي بيانات اعتماد [redacted] يتحقق منها معالجك
Stripe مثال على المزوّد. تنتهي صلاحية عنوان الالتقاط بعد 24 ساعة، أو قبل ذلك إذا حذفت نقطة النهاية. وتفشل التواقيع المقترنة بطابع زمني (Stripe وSlack) في فحص السماحية المعتاد البالغ 5 دقائق إذا أُعيد إرسالها لاحقاً.
مزايا مختبِر Webhook
- عنوان URL فريد للالتقاط يُنشأ بنقرة واحدة، ويُحفظ عبر تحديث الصفحة، وتنتهي صلاحيته بعد 24 ساعة
- استعلام دوري (polling) مباشر كل 3 ثوانٍ ما دام التبويب مرئياً؛ وحالة فارغة تعرض «في انتظار طلب وارد…»
- قائمة طلبات بالطريقة والمسار والوقت والحجم؛ وعرض تفصيلي بملخّص وترويسات مجمّعة وجسم (JSON/نموذج/خام/شجرة) واستعلام وHTTP خام وإعادة إرسال
- اكتشاف المزوّد (Stripe وGitHub وShopify وSlack وTwilio وPayPal وGitLab وBitbucket…) مع نوع الحدث وترويسة التوقيع
- استخراج الحقول المهمة والطوابع الزمنية، ونسخ الحمولة/الترويسات/أمر cURL، وتصدير جميع الالتقاطات بصيغة JSON
- زر إرسال طلب اختباري، وفتح في تبويب جديد، ومسح الالتقاطات، وحذف نقطة النهاية مع عدّ تنازلي لانتهاء الصلاحية
مثال على مختبِر Webhook
التقاط حدث من Stripe
الإدخال:
Stripe → POST https://www.mutqansoft.sa/hooks/3f9c…
Stripe-Signature: t=1725184801,v1=…
{"id":"evt_1PZx…","type":"payment_intent.succeeded",…}النتيجة:
POST / 12:00:01.120 1.4 KB
Provider: Stripe (high confidence) · Event: payment_intent.succeeded · Signature header: Stripe-Signature
Important fields: $.data.object.amount 19900 (199.00 if minor units) · $.data.object.created 1725184790 → 2024-09-01T10:39:50Zالأسئلة الشائعة حول مختبِر Webhook
كم تدوم صلاحية عنوان URL الخاص بي؟
تنتهي صلاحية نقاط نهاية الالتقاط تلقائياً بعد 24 ساعة. ويُحفظ عنوان URL في جلسة متصفحك فيبقى بعد تحديث الصفحة؛ استخدم «حذف نقطة النهاية» لإزالته قبل ذلك.
ما سرعة ظهور الطلبات؟
تستعلم الصفحة كل 3 ثوانٍ ما دام التبويب مرئياً وتتوقف عندما يكون مخفياً، لذا تظهر عمليات التسليم فوراً تقريباً دون إهدار للطلبات.
ما الذي يُلتقط؟
الطريقة والمسار وسلسلة الاستعلام والترويسات والجسم الخام (تُعرض أجسام JSON والنماذج مفكوكة الترميز أيضاً) والحجم وعنوان IP للعميل والوقت الدقيق للاستلام. لا تُسجَّل ترويسات Cookie وcf-*، وتُخزَّن ترويسات بيانات الاعتماد مثل Authorization بالقيمة [redacted]. وتُقتطع الأجسام التي تتجاوز 256 كيلوبايت مع الإشارة إلى ذلك، وتُرفض الأجسام التي تتجاوز 4 ميغابايت بالحالة 413.
هل يمكنني إعادة إرسال تسليم إلى خادمي؟
نعم — ينشئ تبويب إعادة الإرسال أمر cURL موجّهاً إلى عنوان URL الذي تدخله، مع الاحتفاظ بترويسات المزوّد والتوقيع حتى يمكن اختبار كود التحقق لديك، وأنت من يشغّل الأمر. ولأن ترويسات بيانات الاعتماد خُزّنت بالقيمة [redacted]، أعد قيمتها الحقيقية إذا كان المعالج لديك يتحقق منها؛ كما تفشل التواقيع المقترنة بطابع زمني (Stripe وSlack) في فحص السماحية المعتاد البالغ 5 دقائق إذا أُعيد إرسالها لاحقاً.
هل تستجيب نقطة النهاية للمزوّد؟
تردّ بالحالة 200 OK مع جسم JSON صغير، وهو ما يلبّي فحوصات التسليم لدى معظم المزوّدين.
ملاحظات تقنية
ينشئ المتصفح نقطة النهاية عبر POST /api/v1/webhooks، ويحتفظ بالمعرّف/الرمز في sessionStorage، ويستعلم دورياً عبر GET /api/v1/webhooks/:id/requests?after=<last timestamp> مع ترويسة X-Webhook-Token. ويتباطأ الاستعلام الدوري عند حدوث أخطاء ويتوقف عندما يكون التبويب مخفياً.
المراجع
- RFC 9421: HTTP Message Signaturesطريقة قياسية لتوقيع رسائل HTTP بحيث يتحقق المستلم من مصدرها وسلامتها — أساس توقيعات webhook الحديثة.
- RFC 2104: HMAC: Keyed-Hashing for Message Authenticationبناء HMAC: كيف يُنتج مفتاح سري ودالة تجزئة رمز مصادقة للرسالة.
- OWASP Cheat Sheet Series: REST Securityالقواعد الأمنية لواجهات REST: HTTPS، والتوثيق في كل طلب، والتحقق من المدخلات، واستجابات الخطأ الآمنة، وتحديد المعدل.