شرح Webhooks: الحمولات الموقعة وإعادة المحاولات

لقد قمت للتو بدمج بوابة دفع أو خدمة CI/CD، والآن تحتاج إلى استقبال الأحداث في الوقت الفعلي. تُعد Webhooks الحل القياسي، لكنها تأتي مع مخاطر: حمولات غير موثقة، وأحداث مفقودة، وعمليات تسليم مكررة. تشرح هذه المقالة كيفية عمل Webhooks، وكيفية توقيع الحمولات لمنع التلاعب، وكيفية تنفيذ إعادة المحاولات للتسليم الموثوق.

ما هي Webhooks؟

Webhook هو استدعاء HTTP معرف من قبل المستخدم. بدلاً من أن يقوم تطبيقك بالاستعلام عن واجهة برمجة التطبيقات (API) للحصول على التحديثات، يرسل المزود طلب HTTP POST إلى عنوان URL تحدده كلما حدث حدث معين. هذا أكثر كفاءة ويتيح ردود فعل شبه فورية.

تشمل حالات الاستخدام الشائعة:

• إشعارات الدفع (مثل Stripe، PayPal)
• حالة بناء CI/CD (مثل GitHub، GitLab)
• منصات المراسلة (مثل Slack، Discord)
• تحديثات CRM (مثل Salesforce)

لماذا توقيع حمولات Webhook؟

نقاط نهاية Webhook هي عناوين URL متاحة للعامة. بدون التحقق، يمكن لأي شخص إرسال حمولات مزيفة، مما يؤدي إلى تلف البيانات أو اختراقات أمنية. يضمن توقيع الحمولات باستخدام سر مشترك المصادقة والسلامة.

يستخدم معظم المزودين HMAC (رمز المصادقة القائم على التجزئة) مع SHA-256. يحسب المزود توقيعاً على جسم الطلب الخام باستخدام مفتاح سري، ويضمّنه في ترويسة (مثل X-Hub-Signature-256). يعيد خادمك حساب التوقيع ويقارنه.

كيفية التحقق من التوقيع

إليك دليل خطوة بخطوة:

1. استرجع الجسم الخام تماماً كما تم إرساله. لا تقم بتحليله أو تعديله قبل التحقق.
2. استخرج التوقيع من الترويسة.
3. احسب التوقيع المتوقع باستخدام HMAC-SHA256 مع السر الخاص بك.
4. قارن باستخدام دالة زمن ثابت لمنع هجمات التوقيت.

مثال في Node.js:

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = 'sha256=' + hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(digest), Buffer.from(signature));
}

في Python:

import hmac
import hashlib

def verify_signature(payload, signature, secret):
    expected = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(f'sha256={expected}', signature)

استخدم دائماً مقارنة زمن ثابت لتجنب تسريب المعلومات.

تنفيذ إعادة المحاولات للموثوقية

تفشل الشبكات، وتُعاد تشغيل الخوادم، وتحدث عمليات النشر. يجب أن يقوم نظام Webhook القوي بإعادة محاولة التسليمات الفاشلة. عادةً ما يعيد المزودون المحاولة مع تراجع أسي، ولكن يجب عليك أيضاً التعامل مع إعادة المحاولات على جانب الاستقبال.

استراتيجيات إعادة المحاولة

• التراجع الأسي: انتظر 1 ثانية، 2 ثانية، 4 ثوانٍ، 8 ثوانٍ، إلخ، بين المحاولات.
• الحد الأقصى للمحاولات: حدد عدد المحاولات لتجنب الحلقات اللانهائية (مثل 5 محاولات).
• قائمة الرسائل الميتة: بعد الحد الأقصى للمحاولات، خزّن الحدث للفحص اليدوي.
• اللا تكرارية (Idempotency): تأكد من أن معالجة نفس الحدث عدة مرات لا تسبب آثاراً جانبية مكررة.

مفاتيح اللا تكرارية

يتضمن العديد من المزودين معرف حدث فريد (مثل X-Event-ID). خزّن المعرفات المعالجة في قاعدة بيانات أو ذاكرة تخزين مؤقت لتخطي التكرارات. على سبيل المثال، استخدم Redis مع TTL لتتبع المعرفات التي تم رؤيتها.

مقارنة: الاستعلام الدوري مقابل Webhooks

أفضل الممارسات لمستهلكي Webhook

• استجب بسرعة: أعد 2xx خلال ثوانٍ قليلة؛ وعالج بشكل غير متزامن.
• تحقق من التوقيعات: تحقق دائماً قبل المعالجة.
• سجّل كل شيء: احتفظ بالحمولات الخام والترويسات لتصحيح الأخطاء.
• استخدم HTTPS: لا تقبل أبداً Webhooks عبر HTTP العادي.
• راقب الفشل: قم بإعداد تنبيهات لفشل إعادة المحاولات المتكرر.

الأسئلة الشائعة

ما هو توقيع Webhook؟

توقيع Webhook هو تجزئة HMAC للحمولة، تم إنشاؤها باستخدام سر مشترك. يسمح للمستقبل بالتحقق من أن الطلب جاء من المرسل المتوقع ولم يتم التلاعب به.

كم مرة يجب أن أعيد محاولة Webhook فاشل؟

لا يوجد رقم عالمي، لكن 3-5 محاولات مع تراجع أسي أمر شائع. بعد ذلك، سجّل الحدث في قائمة الرسائل الميتة للمراجعة اليدوية.

هل يمكنني استخدام Webhooks بدون HTTPS؟

تقنياً نعم، لكنه غير آمن للغاية. استخدم دائماً HTTPS لتشفير الحمولات ومنع هجمات الوسيط.

هل أنت مستعد لاختبار نقاط نهاية Webhook الخاصة بك؟ استخدم JSON Formatter لفحص الحمولات والتحقق منها بسرعة.