شرح Webhooks: الحمولات الموقعة وإعادة المحاولة
لقد قمت للتو بدمج مزود خدمة دفع أو خدمة CI/CD، والآن تحتاج إلى استقبال الأحداث في الوقت الفعلي. تُعد webhooks الطريقة القياسية لدفع البيانات بين الأنظمة، لكن العديد من التطبيقات تفشل في بيئة الإنتاج بسبب عيوب أمنية أو تسليم غير موثوق. يشرح هذا الدليل كيفية تأمين webhooks باستخدام الحمولات الموقعة وتنفيذ آليات إعادة محاولة قوية.
ما هي webhooks ولماذا هي مهمة
webhook هو استدعاء HTTP: عندما يحدث حدث في نظام المصدر (مثل طلب جديد)، فإنه يرسل طلب HTTP POST إلى عنوان URL تقدمه. على عكس الاستقصاء (polling)، فإن webhooks فعالة وتقريبًا في الوقت الفعلي. ومع ذلك، نظرًا لأنها تعتمد على HTTP، يجب عليك التعامل مع الأمان والموثوقية بشكل صريح.
تشمل حالات الاستخدام الشائعة إشعارات الدفع، ومحفزات خطوط أنابيب CI/CD، وإشعارات الدردشة، ومزامنة البيانات بين تطبيقات SaaS.
تأمين webhooks باستخدام الحمولات الموقعة
webhooks هي نقاط نهاية يمكن الوصول إليها بشكل عام، لذا يمكن للمهاجمين إرسال طلبات مزيفة. لمنع ذلك، يوقع المزودون كل حمولة باستخدام مفتاح سري. يتحقق المستقبل من التوقيع لضمان الأصالة والسلامة.
كيف تعمل توقيعات HMAC
الطريقة الأكثر شيوعًا هي HMAC-SHA256. يحسب المزود تجزئة (hash) لجسم الطلب باستخدام سر مشترك ويضمّنها في رأس (header) مثل X-Signature. يعيد المستقبل حساب التجزئة ويقارنها.
// مثال Node.js: إنشاء توقيع
const crypto = require('crypto');
const secret = 'your_webhook_secret';
const payload = JSON.stringify({ event: 'order.created', id: 123 });
const signature = crypto.createHmac('sha256', secret).update(payload).digest('hex');
// أرسل التوقيع في الرأس: X-Signature: sha256=...
التحقق من التوقيعات على المستقبل
استخدم دائمًا مقارنة ثابتة الوقت لمنع هجمات التوقيت. في Node.js، استخدم crypto.timingSafeEqual.
// مثال برمجية وسيطة Express.js
const crypto = require('crypto');
function verifySignature(req, res, next) {
const signature = req.headers['x-signature'];
const payload = JSON.stringify(req.body); // مطلوب الجسم الخام
const expected = crypto.createHmac('sha256', secret).update(payload).digest('hex');
const trusted = Buffer.from(`sha256=${expected}`, 'utf8');
const received = Buffer.from(signature, 'utf8');
if (trusted.length !== received.length || !crypto.timingSafeEqual(trusted, received)) {
return res.status(401).send('Invalid signature');
}
next();
}
مهم: استخدم جسم الطلب الخام للتحقق، وليس JSON المُحلل، لتجنب التناقضات.
تدابير أمنية إضافية
- التحقق من الطابع الزمني: قم بتضمين طابع زمني في التوقيع وارفض الطلبات الأقدم من بضع دقائق لمنع هجمات إعادة التشغيل.
- HTTPS فقط: استخدم دائمًا نقاط نهاية HTTPS لحماية البيانات أثناء النقل.
- قائمة IP المسموح بها: إذا نشر المزود نطاقات IP، فقم بتقييد الطلبات الواردة لتلك العناوين.
تنفيذ إعادة المحاولة الموثوقة
قد تفشل webhooks بسبب مشكلات الشبكة أو تعطل الخادم أو الأخطاء البرمجية. عادةً ما يعيد المزودون محاولة التسليمات الفاشلة باستخدام تأخير أسي. بصفتك مستقبلًا، يجب أن تكون idempotent وتتعامل مع الأحداث المكررة.
التصميم من أجل Idempotency
يجب أن يكون لكل حدث webhook معرف فريد. قم بتخزين المعرفات المعالجة لتجاهل التكرارات. استخدم قاعدة بيانات بقيد فريد أو ذاكرة تخزين مؤقت مثل Redis.
// كود زائف للمعالجة المتكررة الآمنة (idempotent)
if (await redis.exists(`webhook:${event.id}`)) {
return res.status(200).send('Already processed');
}
await processEvent(event);
await redis.set(`webhook:${event.id}`, '1', 'EX', 86400); // 24h TTL
استراتيجيات إعادة المحاولة
عادةً ما يعيد المزودون المحاولة بتأخيرات متزايدة (مثل 1 ثانية، 5 ثوانٍ، 30 ثانية، 5 دقائق، ساعة). تأكد من أن نقطة النهاية الخاصة بك تستجيب بسرعة (خلال 5 ثوانٍ) لتجنب المهلات. إذا استغرق المعالجة وقتًا أطول، فأقر بالاستلام وقم بالمعالجة بشكل غير متزامن.
إليك مقارنة لأنماط إعادة المحاولة الشائعة:
| النمط | المزايا | العيوب |
|---|---|---|
| فاصل ثابت | بسيط | يمكن أن يرهق خادمًا يتعافى |
| تأخير أسي | يقلل الحمل أثناء الانقطاعات | تأخير في التسليم للأخطاء العابرة |
| تأخير أسي مع تشويش (jitter) | يمنع تأثير القطيع المتصادم | أكثر تعقيدًا قليلاً |
المراقبة وقوائم الرسائل الميتة
قم بتسجيل جميع محاولات webhook والفشل. بعد الحد الأقصى لعدد مرات إعادة المحاولة، انقل الأحداث إلى قائمة رسائل ميتة (DLQ) لفحصها يدويًا. قم بتنبيه عند ارتفاع معدلات الفشل.
تجميع كل شيء معًا: تنفيذ خطوة بخطوة
- إعداد نقطة نهاية HTTPS تقبل طلبات POST وتقرأ الجسم الخام.
- التحقق من التوقيع باستخدام السر المشترك ومقارنة ثابتة الوقت.
- التحقق من الطابع الزمني لمنع هجمات إعادة التشغيل (إذا تم توفيره).
- ضمان Idempotency عن طريق التحقق من معرف الحدث مقابل ذاكرة تخزين مؤقت أو قاعدة بيانات.
- معالجة الحدث بشكل غير متزامن إذا كان قد يستغرق وقتًا؛ استجب بـ 200 OK فورًا.
- تنفيذ منطق إعادة المحاولة على جانب المرسل باستخدام تأخير أسي مع تشويش.
- المراقبة والتنبيه عند الفشل، واستخدم DLQ للأخطاء المستمرة.
الأسئلة الشائعة
ما هي حمولة webhook الموقعة؟
تتضمن الحمولة الموقعة توقيعًا تشفيريًا (عادةً HMAC) يسمح للمستقبل بالتحقق من أن الطلب جاء من مصدر موثوق ولم يتم العبث به.
كيف أتعامل مع أحداث webhook المكررة؟
استخدم معرف الحدث الفريد المقدم في الحمولة لتتبع الأحداث المعالجة. قم بتخزين المعرفات في قاعدة بيانات أو ذاكرة تخزين مؤقت مع TTL لتجاهل التكرارات.
ماذا يجب أن ترجع نقطة نهاية webhook الخاصة بي؟
أرجع رمز حالة 2xx (مثل 200 OK) بسرعة للإقرار بالاستلام. إذا فشلت المعالجة، فأرجع 5xx لتحفيز إعادة المحاولة، ولكن فقط للأخطاء العابرة.
عند اختبار حمولات webhook، قد تحتاج إلى فحص هياكل JSON. استخدم JSON Formatter للتحقق من حمولات webhook وتنسيقها بشكل جميل لتصحيح أسهل.