شرح Webhooks: الحمولات الموقعة وإعادة المحاولة
لماذا تفشل Webhooks في الإنتاج
لقد أنشأت نقطة نهاية webhook واختبرتها محليًا، وكل شيء يعمل. ثم يأتي الإنتاج: يرسل المزود حدثًا مكررًا، أو تنتهي مهلة نقطة النهاية الخاصة بك، أو ينتحل مهاجم طلبًا. فجأة، يصبح تكاملك غير موثوق وغير آمن.
Webhooks بسيطة من حيث المفهوم—استدعاءات HTTP يتم تشغيلها بواسطة الأحداث—لكن التطبيقات الجاهزة للإنتاج تتطلب معالجة دقيقة للأمان والموثوقية. يغطي هذا الدليل جانبين حاسمين: الحمولات الموقعة للتحقق من الأصالة واستراتيجيات إعادة المحاولة للتعامل مع الفشل.
ما هي Webhooks؟
webhook هو استدعاء HTTP معرف من قبل المستخدم. عندما يحدث حدث في نظام مصدر (مثل نجاح عملية دفع)، يرسل طلب HTTP POST إلى عنوان URL تقدمه، يحتوي على بيانات حول الحدث. نموذج الدفع هذا أكثر كفاءة من الاستقصاء.
لكن webhooks تقدم تحديات:
- الأمان: كيف تعرف أن الطلب جاء من المرسل الشرعي؟
- الموثوقية: ماذا لو كانت نقطة النهاية الخاصة بك معطلة أو بطيئة؟
- التكرارات: يمكن أن تسبب الشبكات إعادة المحاولة؛ قد تتلقى نفس الحدث عدة مرات.
لنتناول الأمان أولاً.
تأمين Webhooks باستخدام الحمولات الموقعة
تستخدم الحمولات الموقعة سرًا مشتركًا لإنشاء توقيع تشفيري لنص الطلب. يضمّن المرسل هذا التوقيع في رأس (مثل X-Signature). تعيد نقطة النهاية الخاصة بك حساب التوقيع وتقارنه. إذا تطابقا، فإن الطلب أصلي.
كيف يعمل توقيع HMAC
يستخدم معظم المزودين HMAC-SHA256. يتم حساب التوقيع على نص الطلب الخام باستخدام السر المشترك. إليك التدفق:
- يشترك المزود والمستهلك في مفتاح سري.
- ينشئ المزود الحمولة، ويحسب HMAC-SHA256(secret, payload)، ويرسله في رأس.
- يستقبل المستهلك الطلب، ويقرأ النص الخام، ويحسب نفس HMAC، ويقارن.
هام: استخدم النص الخام تمامًا كما تم استلامه—تحليل JSON وإعادة تسلسله يمكن أن يغير البايتات ويكسر التوقيع.
تنفيذ التحقق من التوقيع
إليك مثال Node.js باستخدام Express:
const crypto = require('crypto');
const express = require('express');
const app = express();
// Use raw body parser for webhook routes
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
const signature = req.headers['x-signature'];
const secret = process.env.WEBHOOK_SECRET;
const expected = crypto
.createHmac('sha256', secret)
.update(req.body)
.digest('hex');
if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
return res.status(401).send('Invalid signature');
}
// Process the event
const event = JSON.parse(req.body);
// ... handle event
res.status(200).send('OK');
});
استخدم دائمًا مقارنة ثابتة الزمن مثل crypto.timingSafeEqual لمنع هجمات التوقيت.
اعتبارات أمان أخرى
- التحقق من الطابع الزمني: قم بتضمين طابع زمني في الحمولة الموقعة وارفض الطلبات القديمة لمنع هجمات إعادة التشغيل.
- HTTPS: استخدم دائمًا HTTPS لنقاط نهاية webhook.
- تدوير السر: دعم أسرار متعددة نشطة للسماح بالتدوير دون توقف.
تنفيذ إعادة المحاولة الموثوقة
حتى مع نقطة نهاية آمنة، يمكن أن تتسبب مشكلات الشبكة أو الأعطال المؤقتة في فشل تسليم webhook. تضمن آلية إعادة المحاولة القوية عدم فقدان الأحداث.
استراتيجية إعادة المحاولة من جانب المرسل
إذا كنت تبني مرسل webhook، فقم بتنفيذ التراجع الأسي مع التذبذب. على سبيل المثال:
- إعادة المحاولة 1: بعد دقيقة واحدة
- إعادة المحاولة 2: بعد 5 دقائق
- إعادة المحاولة 3: بعد 30 دقيقة
- إعادة المحاولة 4: بعد ساعتين
- إعادة المحاولة 5: بعد 24 ساعة
أضف تذبذبًا عشوائيًا لتجنب مشاكل القطيع المتدافع. توقف بعد عدد أقصى من المحاولات وقم بالتنبيه.
أفضل الممارسات من جانب المستقبل
بصفتك مستهلك webhook، لا يمكنك التحكم في سياسة إعادة المحاولة الخاصة بالمرسل، لكن يمكنك جعل نقطة النهاية الخاصة بك مرنة:
- استجب بسرعة: أقر بالاستلام بحالة 2xx قبل معالجة العمل الشاق. استخدم قائمة انتظار.
- الثبات: تعامل مع الأحداث المكررة بسلاسة. استخدم معرف الحدث لإزالة التكرار.
- مراقبة الأعطال: سجل الأعطال وقم بإعداد التنبيهات.
التعامل مع التكرارات باستخدام الثبات
غالبًا ما يعيد مزودو webhook المحاولة عند انتهاء المهلة، لذا قد تتلقى نفس الحدث عدة مرات. اجعل المعالجة الخاصة بك ثابتة:
- قم بتخزين معرفات الأحداث المعالجة في قاعدة بيانات مع قيد فريد.
- قبل المعالجة، تحقق مما إذا كان المعرف موجودًا بالفعل؛ إذا كان كذلك، أعد 200 OK دون إعادة معالجة.
- للعمليات التي تغير الحالة، استخدم مفاتيح الثبات.
مثال باستخدام فهرس فريد في قاعدة البيانات:
async function handleEvent(event) {
try {
await db.query('INSERT INTO processed_events (id) VALUES ($1)', [event.id]);
} catch (err) {
if (err.code === '23505') { // unique violation
return; // already processed
}
throw err;
}
// process event
}
مقارنة: نهج أمان Webhook
| النهج | الإيجابيات | السلبيات |
|---|---|---|
| توقيع HMAC | سلامة قوية، مدعوم على نطاق واسع | يتطلب إدارة الأسرار |
| المصادقة الأساسية | بسيطة | أقل أمانًا، بيانات الاعتماد في الرأس |
| قائمة IP المسموح بها | سهلة التنفيذ | يمكن أن تتغير عناوين IP، ليست قوية |
توقيعات HMAC هي المعيار الفعلي لأمان webhook.
اختبار Webhooks محليًا
أدوات مثل ngrok أو localtunnel تعرض خادمك المحلي للإنترنت للاختبار. اختبر دائمًا التحقق من التوقيع ومنطق إعادة المحاولة مع أعطال محاكاة.
عند فحص حمولات JSON من webhooks، يمكن أن يساعد تنسيقها في التصحيح. جرب JSON Formatter الخاص بنا لطباعة وتنسيق والتحقق من حمولات webhook.
الأسئلة الشائعة
كيف أتحقق من توقيع webhook؟
احسب HMAC لنص الطلب الخام باستخدام السر المشترك، ثم قارنه برأس التوقيع باستخدام دالة مقارنة ثابتة الزمن.
ماذا أفعل إذا كانت نقطة نهاية webhook الخاصة بي معطلة؟
يعيد معظم المزودين المحاولة باستخدام التراجع الأسي. تأكد من أن نقطة النهاية الخاصة بك تعيد 2xx بسرعة وتعالج بشكل غير متزامن لتقليل تأثير التوقف.
هل يمكنني استخدام webhooks بدون توقيعات؟
إنه أمر محفوف بالمخاطر. بدون توقيعات، يمكن للمهاجمين انتحال الطلبات. استخدم دائمًا الحمولات الموقعة أو على الأقل المصادقة الأساسية عبر HTTPS.
الخلاصة
Webhooks قوية ولكنها تتطلب الاهتمام بالأمان والموثوقية. نفذ التحقق من توقيع HMAC لضمان الأصالة، وصمم نظامك للتعامل مع إعادة المحاولة والتكرارات بسلاسة. مع هذه الممارسات، ستكون تكاملات webhook الخاصة بك قوية وجاهزة للإنتاج.