ما هو الـ Webhook؟

الـ Webhook رابط (URL) تمنحه لخدمة خارجية كي ترسل طلب HTTP إلى تطبيقك فور وقوع حدث لديها: دفعة محصَّلة، أو استمارة مُرسَلة، أو طلبية مشحونة. إنه عكس الاستطلاع الدوري (polling): بدل أن تستعلم واجهة برمجية كل خمس دقائق لمعرفة الجديد، تنتظر أن يُخبرك أحد.

التعريف الرسمي

تصوغه وثائق GitHub هكذا: «Webhooks let you subscribe to events happening in a software system and automatically receive a delivery of data to your server whenever those events occur.» أي أن الـ Webhooks تتيح لك الاشتراك في أحداث نظام برمجي واستقبال البيانات آليًا على خادمك كلما وقعت. وتضع المقارنة في الجملة التالية: تُستخدم الـ Webhooks لاستقبال البيانات لحظة حدوثها، «as opposed to polling an API (calling an API intermittently) to see if data is available» (GitHub Docs, About webhooks).

فالكلمة تعني أمرين في آن واحد: الآلية، والرابط الذي يستقبلها. وفي حديث عن الربط التقني، تعني عبارة «أعطني الـ Webhook الخاص بك»: «أعطني العنوان الذي أرسل إليه الأحداث».

ما الذي ينتقل فعليًا

طلب POST، وجسم بصيغة JSON، وبعض الترويسات. لا شيء غريب.

تلخّص Stripe جيدًا ما يتوقّعه منك مُرسِل جادّ: رابط HTTPS متاح للعموم، وTLS 1.2 أو 1.3 فقط، وأي استجابة إعادة توجيه 3xx تُحتسب فشلًا في التسليم (Stripe Docs, Receive Stripe events in your webhook endpoint).

القواعد الثلاث التي نكتشفها متأخرين

أجِب بسرعة، وفكّر بعد ذلك. يجب أن يُرجع رابطك رمز 2xx قبل أي منطق عمل قد يستغرق وقتًا. وتقولها Stripe بلا لبس: يجب إرجاع استجابة 200 قبل تعليم الفاتورة كمدفوعة في أداتك المحاسبية. المعالجة مكانها طابور غير متزامن، لا داخل الطلب.

تحقّق من التوقيع. دون تحقّق، يستطيع أي شخص يعرف رابطك أن يرسل إليك حدث «دفع ناجح» مزيّفًا ويُطلق عملية شحن. توقّع Stripe كل حدث في الترويسة Stripe-Signature بخوارزمية HMAC SHA-256 مع ختم زمني، وتطبّق مكتباتها افتراضيًا هامش تسامح قدره 5 دقائق بين هذا الختم والوقت الحالي — وهذا ما يمنع هجمات إعادة الإرسال. انتبه: يتم التحقّق على الجسم الخام للطلب، وكثير من أطر العمل تعدّله قبل أن يصل إلى الكود الخاص بك.

توقّع التكرار وعدم الترتيب. لا تضمن Stripe ترتيب تسليم الأحداث، وتوصي بتتبّع معرّفاتها لا أختامها الزمنية لاكتشاف التكرار. وعند الفشل، تستمر المحاولات حتى ثلاثة أيام مع تباعد أُسّي. لذلك يجب أن تكون معالجتك متساوية الأثر (idempotent): استقبال الحدث نفسه مرتين يجب ألّا يؤدي إلى الفوترة مرتين.

وعلى صعيد الأدوات دون كود

المبدأ نفسه، دون كتابة خادم. تقبل عقدة Webhook في n8n الطرق DELETE وGET وHEAD وPATCH وPOST وPUT، وتوفّر رابط اختبار منفصلًا عن رابط الإنتاج، وتتيح فرض مصادقة أساسية أو عبر الترويسة أو JWT. الحمولة القصوى 16 ميغابايت، قابلة للتعديل في الاستضافة الذاتية عبر المتغيّر N8N_PAYLOAD_SIZE_MAX (n8n Docs, Webhook node).

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