ويب هوك: نظام خارجي ينادي موقعك، وكودك يشتغل فوراً
الويب هوك في ابني رابط عام لموقعك، أي نظام خارجي يقدر ينادي عليه، وأول ما ينادي يشتغل كود كتبته أنت داخل موقعك. شركة الشحن ترسل الشحنة تسلّمت — الطلب يتحدّث لحاله ويوصل إشعار للزبون. بوابة دفع ترسل الدفعة نجحت — الاشتراك ينفعّل بدون ما تفتح جوالك. الرابط بهذا الشكل: https://اسم-موقعك.ebnii.com/api/site/اسم-موقعك/hook/اسم-الهوك، ويقبل POST وGET. وما ينفتح للعالم إلا ملف اسمه بالضبط functions/<الاسم>-webhook.js — كل دالة ثانية بموقعك تضل خاصة ما حدا يوصلها من برّا.
نُشر في:
ابدأ مجاناًشو الفرق بين ويب هوك ودالة عادية
الدالة العادية ينادي عليها موقعك من الداخل. الويب هوك ينادي عليه العالم الخارجي. هذا الفرق كله، وهو اللي يفرض كل قرار أمني بعده.
التسمية هي المفتاح الأمني. الملف اللي اسمه ينتهي بـ -webhook.js هو الوحيد اللي له رابط عام. باقي دوالك تضل خاصة تماماً ولا يقدر أي حدا ينادي عليها من برّا — حتى لو عرف أسماءها. يعني إنت تقرر شو تفتح، ملف ملف، بمجرد التسمية.
الويب هوك ما يسأل مين أنت. داخله، هوية المستخدم دايماً فاضية — لأن اللي ينادي نظام مو زبون مسجّل دخول. فالتحقق شغلك أنت، والمنصّة تعطيك المادة اللازمة له.
وبيوصلك زيادة عن الدالة العادية: البايتات الأصلية بالضبط كما وصلت، والترويسات بأحرف صغيرة، وباراميترات الرابط، ونوع الطلب. البايتات الأصلية مهمة تحديداً لأن التحقق من توقيع المزوّد يصير عليها هي، مو على نسخة أعيد بناؤها.
رحلة حدث واحد من شركة الشحن لحد إيميل الزبون
الخمس خطوات كلها تصير خلال ثوانٍ وأنت ما فتحت جهازك.
خمسة استخدامات واقعية بالسوق
كل صف منها مبني على نفس المكوّن: رابط هوك واحد + دالة تكتب على قاعدة الموقع.
| النظام الخارجي | شو يرسل | شو يعمل موقعك |
|---|---|---|
| شركة شحن | رقم البوليصة + الحالة الجديدة | يحدّث صف الطلب ويرسل للزبون: طلبك بالطريق |
| بوابة دفع أو مزوّد اشتراكات | الدفعة نجحت أو فشلت | يفعّل الاشتراك أو يفتح الوصول للمحتوى المدفوع |
| خدمة نماذج خارجية | محتوى النموذج المعبّى | يدخل الطلب لقاعدة الموقع بدل ما يضل بصندوق بريد |
| بوت تيليجرام أو واتساب أعمال | الرسالة الواردة من الزبون | يحوّلها لطلب داخل موقعك ويرد بقالب جاهز |
| نظام مخزون أو ERP عندك | تغيّر الكمية المتوفرة | يخفي المنتج الناقص من المتجر لحاله |
من الفكرة للرابط الشغّال
اطلبه بالمحادثة
اكتب: اعمل ويب هوك يستقبل تحديث حالة الشحنة من شركة الشحن ويحدّث الطلب. الوكيل يترجمها لملف ومسار وكود.
الوكيل ينشئ الملف بالاسم الصحيح
مثلاً functions/shipping-webhook.js. اللاحقة -webhook هي اللي تخلي الرابط عام، والوكيل يعرف هالقاعدة ويلتزم فيها.
أضف سرّ التوقيع
المفتاح اللي يعطيك إياه المزوّد ينحفظ كسرّ بالخادم، والدالة تقراه باسمه فقط. ما ينزل للمتصفح ولا يطلع بالسجلات.
انشر الموقع عشان يصير للرابط وجود
رابط الهوك مبني على نطاق موقعك المنشور، فقبل النشر ما في عنوان أصلاً يقدر المزوّد ينادي عليه. والنشر ما يحتاج اشتراك: حتى الخطة المجانية تعطيك رابطاً حقيقياً يستقبل أحداثاً.
الصق الرابط عند المزوّد وجرّب
أغلب المزوّدين عندهم زر إرسال حدث تجريبي. شغّله وراقب السجل داخل الدالة حتى تشوف شو وصل بالضبط قبل ما تعتمد عليه.
ويب هوك على ابني مقابل سيرفر تستأجره
| البند | ويب هوك داخل ابني | سيرفر VPS تديره بنفسك |
|---|---|---|
| الوقت لأول رابط شغّال | دقائق — جملة بالمحادثة ثم نشر | شراء سيرفر ودومين وشهادة SSL ونشر ومراقبة |
| الشهادة والدومين | HTTPS جاهز على نطاق موقعك | تركّبها وتجدّدها بنفسك |
| الوصول لقاعدة موقعك | مباشر بصلاحية صاحب الموقع من داخل الدالة | تكتب طبقة اتصال وتؤمّنها بنفسك |
| الحماية من نداء شبكة داخلية | مفروضة من المنصّة — العناوين الداخلية والميتاداتا مرفوضة | مسؤوليتك بالكامل |
| السقف تحت الضغط | ٦٠ نداء بالدقيقة لكل IP وموقع، و٢٤٠ بالدقيقة للمشروع | حسب حجم السيرفر وإعدادك |
| مكتبات npm | غير متاحة — صندوق QuickJS بلا Node | أي مكتبة تبيها |
| الكلفة الشهرية | ضمن اشتراك ابني بدون فاتورة استضافة منفصلة | فاتورة سيرفر شهرية ثابتة حتى لو ما وصل حدث |
التحقق من التوقيع — شغلك أنت، والمنصّة تعطيك الأدوات
ابني ما يقدر يتحقق من توقيع المزوّد بدالك، لأن كل مزوّد يوقّع بطريقته وباسم ترويسة مختلفة. اللي يعمله ابني: يسلّمك البايتات الأصلية والترويسات كما وصلت، ويرفض معالج ويب هوك واضح إنه ما قرأ مادة التوقيع أصلاً.
الطريقة الصحيحة بثلاث حركات: اجلب مفتاح التوقيع من الأسرار، احسب HMAC على البايتات الأصلية، وقارن الناتج بترويسة المزوّد باستخدام مقارنة ثابتة الزمن (ebnii.crypto.timingSafeEqual).
ممنوعان شائعان: لا تقارن بعلامة يساوي العادية — المقارنة العادية تسرّب معلومات عبر فروق التوقيت. ولا تعيد بناء النص بتحويل الحمولة لـ JSON من جديد — ترتيب المفاتيح والمسافات بيطلع مختلف عن اللي وقّعه المزوّد، فالتحقق يفشل بلا سبب واضح أو يمر وهو غلط.
عندك بالصندوق كمان: توليد تجزئة، أرقام عشوائية آمنة، معرّفات فريدة، توقيع والتحقق من JWT بـ HS256 وRS256، وقراءة Basic Auth. يعني أغلب مخططات التحقق اللي يستخدمها المزوّدون مغطّاة بلا مكتبة خارجية.
ونصيحة عملية أخيرة: خلي الدالة ترد بسرعة. المزوّدون يعيدون الإرسال إذا تأخرت، فتنتهي بأحداث مكررة. استقبل، تحقق، احفظ، ورجّع رد فوري — وأي شغل تقيل صفّه كمهمة مؤجّلة.
حدود الويب هوك
كلها أرقام مفروضة من المنصّة، وأفضل تصمّم عليها من البداية بدل ما تكتشفها بالإنتاج.
الاسم يحدد النشر
بس functions/<الاسم>-webhook.js له رابط عام. أي ملف ثاني يضل خاص. لا تسمّي دالة داخلية بلاحقة webhook إلا إذا فعلاً بدك تفتحها للعالم.
الموقع لازم يكون منشور
رابط الهوك ما يشتغل قبل النشر. اختبر بعد ما تنشر، بالحدث التجريبي اللي يوفّره المزوّد.
عشر ثوانٍ للتنفيذ
النداء الخارجي مهلته ١٠ ثوانٍ، وبعدها توقف الدالة برسالة انتهت مهلة التنفيذ. الشغل الطويل ينرحّل لمهمة مؤجّلة، وهي تعيد ٣ محاولات بتباعد زمني قبل ما تُعتبر فاشلة.
ثماني نداءات خارجية وخمس رسائل
بالتشغيلة الواحدة. يعني هوك يستقبل حدث ويرسل ١٠ إيميلات مرّة وحدة تصميم غلط — قسّمه على مهام مؤجّلة.
أحجام مقفولة
الحمولة الداخلة حتى ١٠٠ كيلوبايت، وكود الدالة حتى ١٠٠ كيلوبايت، والرد الخارجي اللي تجيبه حتى ٢ ميغابايت.
سقوف النداء
٦٠ نداء بالدقيقة لكل IP وموقع، و٢٤٠ بالدقيقة للمشروع كامل. المزوّد اللي يرسل دفعات ضخمة بيتم تحجيمه ولازم يعيد لاحقاً.
ما في هوية داخل الهوك
هوية المستخدم فاضية دائماً. اعتمد على توقيع المزوّد أو على Basic Auth، ولا تبني منطقك على إن اللي نادى مسجّل دخول.
ما في مزوّد إيميل خارجي
الإرسال من داخل الدالة عبر أداة المنصّة فقط، وهي توصل لأي عنوان. مزوّدات البريد الخارجية محجوبة على مستوى الشبكة برسالة صريحة.
أسئلة شائعة
اقرأ أيضاً
خلي شركة الشحن تحدّث طلباتك بدالك
اكتب بالمحادثة: اعمل ويب هوك يستقبل حالة الشحنة ويحدّث الطلب ويرسل إشعار للزبون — وانسخ الرابط للمزوّد بعد النشر.
ابدأ مجاناً