فاحص نقاط نهاية Webhook

ما الذي يجب أن تفعله نقطة نهاية الـ Webhook لتستقبل التسليمات بموثوقية؟

أن تجيب عن طلب POST عبر HTTPS بإجابة 2xx بسرعة — فمزوّدون مثل GitHub يتوقعونها خلال 10 ثوانٍ — عند الرابط المسجّل بالضبط، لأن كثيراً من المرسِلين لا يتتبّعون إعادة التوجيه ويعدّون كل ما سوى 2xx فشلاً يُعاد لاحقاً. وعليها أن تتحقق من توقيع المرسِل على الجسم الخام قبل التصرّف، وأن ترفض الطلبات غير الموقّعة، وأن تنجز العمل الفعلي بعد الإقرار بالاستلام، كي لا تتسبّب المعالجة البطيئة في تسليمات مكررة.

ملاحظة أمنية: رابط الـ Webhook عام: يستطيع كل من يعرفه أن يرسل إليه. تحقّق من التوقيع بمقارنة ثابتة الزمن، وارفض الطوابع الزمنية القديمة، ولا تعامل الحمولة أبداً كمدخل موثوق.

كيفية استخدام فاحص نقاط نهاية Webhook

1. أدخل الرابط الذي سجّلته (أو ستسجّله) لدى مزوّد الـ Webhook، مثل https://api.example.com/webhooks/incoming.
2. اضغط «افحص نقطة النهاية»، فيرسل خادم متقن طلب POST التجريبي وطلب OPTIONS مرة واحدة لكل منهما.
3. اقرأ «ما يراه مرسِل الـ Webhook» من الأعلى: يخبرك الصف الأول هل كان التسليم سيُحتسب.
4. إن رفضت نقطة النهاية الاختبار غير الموقّع بـ 400 أو 401 أو 403 فهذا متوقع من نقطة موقّعة؛ أرسل حدثاً تجريبياً موقّعاً من لوحة المزوّد لفحص مسار القبول.

مزايا فاحص نقاط نهاية Webhook

• يرسل تسليماً اختبارياً واحداً كما يفعل مزوّد الـ Webhook — طلب POST بصيغة JSON — مع طلب OPTIONS واحد، ويعرض كيف أجابت نقطة النهاية
• يشرح رمز الحالة كما سيعامله المرسِل: تسليم ناجح (2xx)، أو إعادة توجيه تضيع معها الرسالة، أو رفض لأن النقطة موقّعة (400 و401 و403)، أو غير موجود، أو غير مسموح، أو فشل (5xx)
• يقيس زمن الإجابة وينبّه إلى ما يتجاوز 3 ثوانٍ، وهي النقطة التي يبدأ عندها المرسِلون بالاستسلام وإعادة المحاولة
• يكشف HTTP غير المشفّر، وإعادة التوجيه (مع وجهتها، دون تتبّعها)، وغياب Content-Type، وترويسة Retry-After
• يعرض ترويسات الإجابة المهمة للـ Webhooks وأول 2048 حرفاً من الرد كنص
• يعرض بالضبط ما أُرسل: جسم ثابت بمعرّف عشوائي ووقت الفحص، لا بياناتك ولا حدثاً حقيقياً أبداً

المدخلات والمخرجات

المدخلات

• رابط الـ Webhook — عنوان http:// أو https:// يسلّم إليه المزوّد؛ ويُضاف https:// إلى «example.com/hook». وتُرفض أسماء المستخدمين وكلمات المرور داخل الرابط.
• لا شيء غيره: الطريقة والترويسات والجسم ثابتة ولا يمكن تغييرها.

المخرجات

• الملخص — رمز حالة طلب POST، والزمن الذي استغرقه، وهل الرابط HTTPS، ورمز حالة طلب OPTIONS.
• ما يراه مرسِل الـ Webhook — كل فحص مع نتيجته: التسليم، وHTTPS، وزمن الاستجابة، وContent-Type، وإجابة OPTIONS، وRetry-After.
• ترويسات الاستجابة ومحتواها — الترويسات المهمة للـ Webhooks ‏(Content-Type وServer وAllow وRetry-After وX-Request-Id وCORS) وأول 2048 حرفاً من الرد، معروضة كنص.
• ما أُرسل وعن هذا الفحص — الطلبان كما يرسلهما الخادم بالضبط، وما لا يستطيع الفحص معرفته.

مثال على فاحص نقاط نهاية Webhook

https://hooks.example.com/payments/events

الملخص: رمز حالة HTTP ‏401 · زمن الاستجابة 184 ms · مشفّر (HTTPS) نعم · إجابة OPTIONS ‏204
ما يراه مرسِل الـ Webhook: يقبل طلب POST التجريبي — معلومات (رُفض، وهذا صحيح لنقطة نهاية تتحقق من توقيع أو رمز) · HTTPS — ناجح · زمن الاستجابة — ناجح (خلال 3 ثوانٍ) · Content-Type في الإجابة — معلومات · طلب OPTIONS — معلومات
ترويسات الاستجابة: content-type ‏application/json · x-request-id ‏7f3c9a
محتوى الاستجابة: {"error":"invalid signature"}

كيف تقرأ نتائج فاحص نقاط نهاية Webhook

«ناجح» في الصف الأول (2xx) يعني أن التسليم الحقيقي سيُقبل غالباً أيضاً، ما لم تكن نقطة النهاية تتحقق من شيء لا يستطيع هذا الاختبار إرساله، كالتوقيع.

«معلومات» مع 400 أو 401 أو 403 هي الإجابة المتوقعة من نقطة نهاية تتحقق من التواقيع أو الرموز: المسار موجود ويحمي نفسه. لكنها ليست دليلاً على أن الأحداث الحقيقية ستمرّ.

«فشل» مع إعادة توجيه يعني أن التسليمات لا تصل إلى أي مكان؛ سجّل الرابط الذي يشير إليه التوجيه. و«فشل» مع 404 أو 405 يعني عادةً مساراً خاطئاً أو مساراً لا يقبل إلا GET.

زمن استجابة يتجاوز 3 ثوانٍ تحذير لا فشل: يختلف المرسِلون، لكن معظمهم يتوقف بعد 5 إلى 10 ثوانٍ ويعيد المحاولة، وقد يصل الحدث نفسه مرتين.

متى تستخدم فاحص نقاط نهاية Webhook

• قبل تسجيل رابط Webhook لدى مزوّد مدفوعات أو Git أو مراسلة: هل يمكن الوصول إليه، وهل هو HTTPS وسريع ولا يعيد التوجيه؟
• بعد نشر نسخة جديدة أو تغيير في DNS، حين تبدأ التسليمات بالفشل بانتهاء المهلة أو بـ 404.
• التأكد من أن نقطة النهاية الموقّعة ترفض الطلبات غير الموقّعة بدلاً من معالجتها.
• فحص مستقبِل خلف وسيط أو بوابة API قد تضيف إعادة توجيه أو تبطئه.

استكشاف الأخطاء وإصلاحها

• «لم تُجب نقطة النهاية في الوقت المحدد»: لم يُجب شيء خلال 10 ثوانٍ. تأكد من أن الخدمة تعمل ويمكن الوصول إليها من الإنترنت، لا من شبكتك فقط.
• «فحوص الـ Webhook محدودة بعشرين فحصاً كل 10 دقائق للعنوان الواحد»: انتظر المدة المذكورة؛ فهذا الحد يحمي نقاط النهاية التي تُختبر.
• الإجابة صفحة HTML مع 403: جدار حماية أو نظام مكافحة روبوتات يجيب لا تطبيقك. اسمح بعناوين المزوّد كما تسردها وثائقه.
• شغّل الاختبار معالجك: نقطة النهاية تقبل JSON غير موقّع. تجاهل النوع mutqan.webhook_check أو الترويسة X-Mutqan-Webhook-Check، وفكّر في اشتراط التوقيع.

الأسئلة الشائعة حول فاحص نقاط نهاية Webhook

ملاحظات تقنية

الـ Webhook طلب HTTP POST يرسله مزوّد إلى رابط تسجّله. ويعدّ المرسِلون أي إجابة 2xx تسليماً، وكل ما عداها — 3xx أو 4xx أو 5xx أو انتهاء المهلة — فشلاً يُعاد لاحقاً (ويعرّف RFC 9110 فئات الحالة). وكثير منهم لا يتتبّع إعادة التوجيه، والعميل الذي يتتبّعها قد يحوّل POST إلى GET بعد 301 أو 302 ‏(RFC 9110 §15.4) فيضيع الجسم.

يجري الفحص طلبين فقط من خادم متقن: POST يحمل Content-Type: application/json ووكيل المستخدم MutqanTools-WebhookCheck/1.0 وX-Mutqan-Webhook-Check: 1 والجسم {"type":"mutqan.webhook_check","id":…,"sentAt":…}، ثم OPTIONS بالترويستين التعريفيتين نفسيهما، ويضيف الوسيط ترويسته X-Mutqan-Relay: 1 إلى الطلبين. ويجب أن يُحلّ المضيف إلى عناوين عامة فقط، وينتظر كل طلب حتى 10 ثوانٍ، ولا تُتبع إعادة التوجيه.

تضع الـ Webhooks الموقّعة رمز HMAC أو توقيعاً على الجسم الخام في ترويسة (وتوحّد مواصفة HTTP Message Signatures ‏RFC 9421 أحد أشكاله). ولأن هذا الاختبار غير موقّع فإن المستقبِل المبني بشكل صحيح يرفضه؛ ويساعدك محلّل توقيعات Webhook على التحقق من توقيع التقطته.

الحدود ومنهجية القياس

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

التسليم الواحد لقطة من شبكة خادم متقن؛ أما المزوّدون فيرسلون من عناوينهم الخاصة، وقد يعاملها جدار الحماية معاملة مختلفة، ويعيدون المحاولة وفق جدولهم.

لا يُعرض إلا أول 2048 حرفاً من الرد وجزء من ترويساته؛ ولا يمكن رؤية ما تفعله نقطة النهاية بعد أن تجيب.

الأمان والخصوصية

لا يغادر متصفحك إلا الرابط. ويرسل خادم متقن إلى نقطة النهاية جسماً اختبارياً ثابتاً بمعرّف عشوائي ووقت الفحص، لا بياناتك أبداً، ولا يخزّن شيئاً؛ فلا تستخدمه إلا مع نقاط نهاية مسموح لك باختبارها.

المراجع

• Best practices for using webhooksGitHub Docsقواعد مزوّد لمستقبِلي الـ Webhooks: استخدام HTTPS، والتحقق من السر المشترك، والإجابة بـ 2xx خلال 10 ثوانٍ مع المعالجة غير المتزامنة، والتعامل مع إعادة التسليم.
• RFC 9110: HTTP SemanticsIETF · 2022معاني أساليب HTTP وحقول الترويسات ورموز الحالة والتفاوض على المحتوى، بغضّ النظر عن إصدار البروتوكول.
• RFC 9421: HTTP Message SignaturesIETF · 2024طريقة قياسية لتوقيع رسائل HTTP بحيث يتحقق المستلم من مصدرها وسلامتها — أساس توقيعات webhook الحديثة.