Webhooks الصادرة: أصعب ما تبنيه لأن الفشل يقع عند غيرك
التوقيع، وإعادة المحاولة، والترتيب، والمستقبِل البطيء — لماذا يبدو إرسال طلب HTTP بسيطاً حتى تُرسله لألف عميل.
استقبال ويبهوك سهل. إرساله صعب — لأنك تعتمد على خادم لا تملكه، قد يكون بطيئاً أو معطّلاً أو يعيد ٢٠٠ ثم يتجاهل الرسالة. وكل ذلك مسؤوليتك من وجهة نظر عميلك.
وقّع كل حمولة
المستقبِل يحتاج التأكّد أن الطلب منك فعلاً. أرسل توقيع HMAC للحمولة الخام مع طابع زمني في الترويسة، ووثّق كيف يُحسب. ضمّن الطابع في المحتوى الموقَّع، وإلا أمكن إعادة تشغيل رسالة قديمة بتوقيعها الصحيح. واطلب من المستقبِل رفض ما تجاوز نافذة زمنية قصيرة.
افترض التكرار وصرّح به
التسليم مرة واحدة بالضبط غير قابل للتحقيق عملياً عبر الشبكة. أرسل معرّفاً فريداً لكل حدث، ووثّق صراحةً أن على المستقبِل تجاهل ما عالجه. هذا ليس تنازلاً، بل عقد واضح — والبديل هو عميل يظن أن التكرار عطل في نظامك.
إعادة المحاولة والفشل النهائي
- أعد المحاولة بتباعد متزايد على مدى ساعات، لا دقائق — أغلب الأعطال قصيرة لكنها ليست ثوانيَ.
- اعتبر ٢xx نجاحاً فقط، و٤xx فشلاً دائماً لا يستحق إعادة، و٥xx مؤقّتاً يستحقها.
- ضع مهلة قصيرة على الاستجابة؛ مستقبِل بطيء لا يجب أن يعطّل طابورك كله.
- أوقف نقطة النهاية تلقائياً بعد فشل متواصل طويل، وأبلغ العميل — الإرسال إلى عنوان ميت لأسابيع هدر خالص.
نقطة نهاية عميل معطّلة منذ شهر لا يجب أن تكلّفك محاولة كل دقيقة إلى الأبد.
الترتيب ليس مضموناً — قل ذلك
الحدث «تم التحديث» قد يصل قبل «تم الإنشاء» بسبب إعادة محاولة. أرفق طابعاً زمنياً ورقم تسلسل، ووثّق أن على المستقبِل الاعتماد عليهما لا على ترتيب الوصول. ضمان الترتيب الصارم يكلّف كثيراً وأغلب الحالات لا تحتاجه.
أعطِ العميل أدوات التشخيص
سجّل كل محاولة تسليم مع رمز الاستجابة والزمن، واعرضها للعميل. أضف زر إعادة إرسال يدوي وأداة اختبار ترسل حدثاً تجريبياً. هذه الثلاثة تختصر أغلب تذاكر الدعم في التكاملات، لأنها تحوّل «لا يعمل» إلى معلومة.
لا تخترع صيغة توقيع خاصة بك: Standard Webhooks مواصفة مفتوحة تغطّي التوقيع والطابع الزمني ومنع إعادة التشغيل، وRFC 9421 لتوقيعات رسائل HTTP هو المعيار الرسمي لمن يحتاج شيئاً أشمل.
وإن كنت تبني نظام ويبهوكس لمنتجك، فالتوقيع ومنع إعادة التشغيل هما ما يُنسى غالباً. تحدّث إلينا.
أسئلة شائعة
هل أرسل البيانات كاملة أم معرّفاً فقط؟
أرسل ما يكفي للتصرّف دون استدعاء إضافي، وتجنّب البيانات الحسّاسة. المعرّف وحده يضاعف الطلبات على واجهتك.
كيف أدير تدوير المفاتيح؟
اسمح بمفتاحين نشطين معاً لفترة، فيستطيع العميل التبديل دون انقطاع.
ماذا لو أراد العميل عناوين متعدّدة؟
ادعمها مع اختيار الأحداث لكل عنوان؛ إرسال كل شيء إلى كل مكان يهدر موارد الطرفين.