الـWebhooks: إرسال الطلبيات واستقبال الحالات

الـwebhook مشروحا بدون مصطلحات تقنية

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

وتقنيا، «العنوان» هو رابط في موقعك، و«النداء» هو طلب ويب يحمل معلومات الحدث. هذا كل شيء. ولا يوجد أي سحر آخر، ولهذا يعمل الـwebhook مع أي لغة وأي استضافة: فإذا كان موقعك يعرف كيف يستقبل استمارة فهو يعرف كيف يستقبل webhook.

ومن هذه البساطة تنتج نتيجتان، وهما تشرحان بقية هذه الصفحة. الأولى: ما دام أي شخص يقدر ينادي عنوانا، فلا بد من وسيلة تُثبت أن النداء يأتي فعلا من يدّعي ذلك — وهي التوقيع. والثانية: ما دام النداء قد يفشل، فلا بد من وسيلة لإعادته — وهي الإعادات.

الاتجاه الوارد: طلبياتك تصل إلينا

هذه هي طريقة دخول الأدوات التي لا تظهر في أي لائحة تكاملات. تُنشئ ربطا، فتُعطيك المنصة عنوانا فريدا، وتناديه أداتك عند كل طلبية. والصيغة المنتظرة هي نفسها صيغة الـAPI: اسم الزبون، والهاتف، والمدينة، والعنوان، والمبلغ الذي يجب تحصيله، والمنتجات بـSKU والكمية، ومرجع طلبيتك.

وإذا كانت أداتك تُرسل صيغة مختلفة — وهذا كثير مع موقع خاص أو أداة أتمتة — فإن المنصة لا تُخمّن شيئا. أول إرسال يُحفظ كنموذج، وتقترح عليك ربط كل حقل من حقولك بالحقل المقابل، والطلبيات الواصلة في الأثناء تُعاد بترتيب وصولها بمجرد تسجيل الربط. وهي نفس الآلية المستعملة في المتجر المربوط.

وبعد قراءة الطلبية تمر من نفس المراقبات التي يمر منها كل شيء آخر: الهاتف يُوحّد، والمدينة تُقارب، وSKU يُتحقق منه، والمبلغ الإجمالي يُقارن بمجموع الأثمنة. والطلبية الناقصة تصبح ليدا معطوبا بدل أن تُرفض. والطلبية التي سبق وصولها، لأن أداتك أعادت الإرسال، لا تُنشئ ليدا ثانيا: فمعرّفها محفوظ لكل ربط.

الاتجاه الصادر: مراحل الطلبية تصل إليك

في الاتجاه الآخر، تُسجّل عنوان نظامك وتختار ما تريد معرفته. وفي كل مرة تجتاز إحدى طلبياتك مرحلة، يُنادى عنوانك بتفاصيل الطلبية: مرجعها، ومرجعك، والزبون، والمبلغ الإجمالي، وربح البائع، والحالات، ورقم التتبع عندما يكون موجودا.

التوقيع، ولماذا لا يكفي عنوان سري

الاستنتاج الطبيعي هو أن عنوانا لا يعرفه أحد يقوم مقام كلمة سر. وهذا خاطئ، لسبب بسيط: العنوان يتحرك. يظهر في سجل سيرفور، وفي صورة شاشة، وفي رسالة إلى مزوّد خدمة، وفي تاريخ أداة أتمتة. وكل من رآه يقدر يُرسل «طلبية موصّلة» كاذبة إلى نظامك، وستُصدّقها حساباتك.

والتوقيع يحل هذا. في كل إرسال، يحسب المُرسل بصمة للمحتوى بمفتاح سري لا تعرفه إلا الجهتان، ويضعها في ترويسة. والمستقبل يُعيد حساب نفس البصمة من جهته ويقارن. وما دام المفتاح السري لا يتحرك أبدا، فلا أحد يقدر يصنع بصمة صحيحة — ولو عرف العنوان، ولو عرف المحتوى الذي يجب تقليده بالضبط.

والإرسالات الصادرة من المنصة موقّعة على الطابع الزمني والمحتوى الخام معا، والطابع الزمني يُمرّر في ترويسة خاصة به. وهذه المعلومة المزدوجة تسمح لك برفض شيئين مختلفين: محتوى مُعدَّل، لأن البصمة لن تتطابق؛ ومحتوى صحيح لكنه أُعيد بعد ساعات، لأن الطابع الزمني سيكون قديما جدا. والمفتاح السري يُعرض مرة واحدة فقط، في اللحظة التي يُنشأ فيها العنوان.

وفي الاتجاه الوارد ينطبق نفس المبدأ بالمقابل: تختار مفتاحا سريا، وتضعه في الجهتين، وتُوقّع محتوى إرسالاتك. وإذا لم تضع مفتاحا سريا فإن العنوان السري يبقى حمايتك الوحيدة — وهذا مقبول في البداية، وغير كافٍ بمجرد أن يُشارَك العنوان مرة واحدة.

الفشل والإعادات والتعطيل

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

والإرسال ينجح عندما يُجيب سيرفورك برمز نجاح. وإلا فيُعاد لاحقا، بفترات تتباعد أكثر وأكثر، على مدى بضع ساعات. فالسيرفور المطفأ ليلة واحدة يجد أحداثه في الصباح، دون أن يُنادى ألف مرة في الأثناء. وبعد عدد من المحاولات يُترك الإرسال ويُسجّل كفاشل.

وإذا فشل عنوانك بشكل متكرر على سلسلة طويلة من الإرسالات، فإنه يُعطَّل تلقائيا: فالسيرفور الذي اختفى نهائيا لا يجب أن يُنادى إلى ما لا نهاية. ويُعاد تفعيله بنقرة واحدة بعد إصلاح سيرفورك. وفي الأثناء، تُظهر لائحة آخر الإرسالات ما خرج وما فشل وبأي رمز جواب — وهي التي تُجيب عن سؤال «علاش نظامي ما توصل بحتى شي حاجة».

• أجب بسرعة — سجّل الحدث، وأجب بالنجاح، ثم عالج. فالمعالجة قبل الجواب تنتهي بتجاوز مدة الانتظار.
• اقبل التكرار — نفس الحدث قد يصل مرتين إذا ضاع جوابك في الطريق. وكودك يجب أن يقدر على استقباله مرتين بدون أي أثر.
• ارفض ما بقي — توقيع غير صحيح، أو طابع زمني قديم، أو حدث غير معروف: أجب بخطأ ولا تُعالج شيئا.
• عنوان عمومي بـHTTPS — العنوان المحلي أو الخاص يُرفض عند التسجيل: فهو سيجعلنا ننادي آلة ليست آلتك.

متى يكون الـwebhook أفضل من متجر مربوط

إذا كان هناك تكامل رسمي لمتجرك فاستعمله: فهو يشترك وحده، ويُسيّر تجديد الدخول، وعنده قراءة احتياطية إذا ضاع إشعار. أما الـwebhook الذي تبنيه بنفسك فليس عنده هذه الشبكة، إلا إذا كتبتها أنت.

• أداتك ليس لها تكامل — وهذه هي الحالة النموذجية: موقع خاص، أو قمع بيع، أو أداة تسيير داخلية. والـwebhook هو الطريق الأقصر.
• تمر عبر أداة أتمتة — الموصّل الوسيط يعرف كيف يُطلق على «طلبية جديدة» ويُرسل طلبا: فلا تكتب ولو سطرا من الكود.
• تريد أن تُخبَر بالحالات — وهو الوسيلة الوحيدة لمعرفة توصيل دون استجواب الـAPI في حلقة، وليس له مقابل في جهة المتاجر المربوطة.
• تحتاج قراءة شيء آخر — الـwebhook يُعلن حدثا؛ ولا يسمح باستجواب الكاطالوغ أو المدن أو الأرشيف. ولهذا تحتاج الـAPI.