شرح Webhooks: الحمولات الموقعة وإعادة المحاولة الموثوقة
لقد قمت للتو بدمج خدمة طرف ثالث ترسل webhooks إلى نقطة النهاية الخاصة بك. كل شيء يعمل في الاختبار، ولكن في الإنتاج، لاحظت أحداثًا مفقودة، وتسليمات مكررة، وحتى طلبات مزورة. webhooks بسيطة من حيث المفهوم ولكنها صعبة التنفيذ بشكل صحيح. تشرح هذه المقالة كيفية تأمين webhooks باستخدام الحمولات الموقعة وتنفيذ منطق إعادة المحاولة الموثوق حتى تكون تكاملاتك قوية وموثوقة.
ما هي Webhooks ولماذا تهم
webhooks هي عمليات استدعاء HTTP محددة من قبل المستخدم يتم تشغيلها بواسطة الأحداث. بدلاً من الاستقصاء (polling) عن التغييرات في API، تقوم بتسجيل عنوان URL، وترسل الخدمة طلب POST مع بيانات الحدث كلما حدث شيء ما. يقلل نموذج الدفع هذا من زمن الوصول وحمل الخادم، مما يجعله مثاليًا للتكاملات في الوقت الفعلي مثل إشعارات الدفع، ومحفزات CI/CD، ورسائل الدردشة.
ومع ذلك، تقدم webhooks تحديات: التحقق من الأصالة، والتعامل مع حالات الفشل، وضمان المعالجة مرة واحدة بالضبط. دعنا نتعامل مع هذه واحدة تلو الأخرى.
تأمين Webhooks باستخدام الحمولات الموقعة
بدون التحقق، يمكن لأي شخص إرسال طلبات مزيفة إلى نقطة نهاية webhook الخاصة بك. تحل الحمولات الموقعة هذه المشكلة عن طريق تضمين توقيع تشفيري في رؤوس الطلب، يتم إنشاؤه باستخدام سر مشترك. يمكنك التحقق من التوقيع لتأكيد أن الطلب جاء من المرسل المتوقع ولم يتم التلاعب به.
كيف تعمل توقيعات HMAC
تستخدم معظم الخدمات HMAC (رمز مصادقة الرسائل القائم على التجزئة) مع SHA-256. يحسب المرسل تجزئة لجسم الطلب (وأحيانًا طابع زمني) باستخدام السر، ويضمّنها في رأس مثل X-Signature. تقوم بإعادة حساب التجزئة من جانبك ومقارنتها.
إليك تدفق تحقق نموذجي في Node.js:
const crypto = require('crypto');
function verifySignature(payload, signature, secret) {
const expected = crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expected)
);
}
استخدم دائمًا مقارنة آمنة زمنيًا لمنع هجمات التوقيت. أيضًا، قم بتضمين طابع زمني في البيانات الموقعة وارفض الطلبات الأقدم من بضع دقائق لمنع هجمات إعادة التشغيل.
أفضل الممارسات للتحقق من التوقيع
- استخدم HTTPS لحماية الحمولة أثناء النقل.
- قم بتخزين الأسرار بشكل آمن (على سبيل المثال، متغيرات البيئة، مديري الأسرار).
- تحقق من الطابع الزمني وارفض الطلبات القديمة.
- سجل حالات فشل التحقق للمراقبة.
تنفيذ إعادة المحاولة الموثوقة
تفشل الشبكات، وتعيد الخوادم التشغيل، وتنتهي مهل نقاط النهاية. يجب على نظام webhook القوي إعادة محاولة التسليمات الفاشلة. لكن إعادة المحاولة يمكن أن تسبب تكرارات، لذلك تحتاج إلى idempotency.
استراتيجيات إعادة المحاولة
يستخدم معظم المزودين التراجع الأسي مع التذبذب. على سبيل المثال، أعد المحاولة بعد دقيقة واحدة، ثم 5 دقائق، ثم 30 دقيقة، حتى الحد الأقصى لعدد المحاولات (على سبيل المثال، 5). قم بتضمين معرف حدث فريد في الحمولة حتى يتمكن المتلقي من إزالة التكرار.
من جانب الاستقبال، استجب بسرعة بحالة 2xx لتأكيد الاستلام، ثم قم بالمعالجة بشكل غير متزامن. إذا فشلت المعالجة، لا يمكنك الاعتماد على المرسل لإعادة المحاولة إلى أجل غير مسمى - قم بتنفيذ قائمة انتظار الرسائل الميتة الخاصة بك أو التنبيهات.
مفاتيح Idempotency
للتعامل مع التسليمات المكررة، استخدم مفتاح idempotency (غالبًا معرف الحدث) وقم بتخزين المعرفات المعالجة لفترة معقولة. قبل المعالجة، تحقق مما إذا كان المعرف قد تم رؤيته؛ إذا كان الأمر كذلك، فأرجع النجاح دون إعادة المعالجة.
// Example: idempotency check in Express
app.post('/webhook', async (req, res) => {
const eventId = req.body.id;
if (await db.seenEvents.has(eventId)) {
return res.status(200).send('Already processed');
}
await db.seenEvents.add(eventId);
// process event asynchronously
res.status(200).send('OK');
});
مقارنة: الاستقصاء مقابل Webhooks
| الجانب | الاستقصاء | Webhooks |
|---|---|---|
| زمن الوصول | مرتفع (على أساس الفاصل الزمني) | منخفض (شبه فوري) |
| حمل الخادم | مرتفع (طلبات متكررة) | منخفض (مدفوع بالأحداث) |
| التعقيد | بسيط التنفيذ | يتطلب التحقق من التوقيع وإعادة المحاولة |
| الموثوقية | تعتمد على تردد الاستقصاء | تعتمد على آلية إعادة المحاولة |
خطوة بخطوة: بناء مستقبل webhook آمن
- قم بإعداد نقطة نهاية تقبل طلبات POST عبر HTTPS.
- تحقق من التوقيع باستخدام السر المشترك وارفض الطلبات غير الصالحة بحالة 401.
- تحقق من الطابع الزمني لمنع هجمات إعادة التشغيل.
- استجب فورًا بحالة 200 OK بعد التحقق الأساسي، ثم قم بالمعالجة بشكل غير متزامن.
- قم بتنفيذ idempotency باستخدام معرفات الأحداث لتجنب المعالجة المكررة.
- سجل وراقب حالات الفشل وإعادة المحاولة.
الأسئلة الشائعة
ما هي حمولة webhook الموقعة؟
تتضمن الحمولة الموقعة توقيعًا تشفيريًا (عادة HMAC) يسمح للمستقبل بالتحقق من أصالة الطلب وسلامته باستخدام سر مشترك.
كم مرة يجب أن أعيد محاولة webhook فاشل؟
الممارسة الشائعة هي 3-5 محاولات إعادة مع التراجع الأسي. بعد ذلك، انقل الحدث إلى قائمة انتظار الرسائل الميتة للفحص اليدوي.
هل يمكنني استخدام webhooks بدون HTTPS؟
لا، HTTPS ضروري لحماية الحمولة والتوقيع من التنصت والتلاعب. استخدم دائمًا TLS.
هل أنت مستعد لاختبار حمولات webhook الخاصة بك؟ استخدم منسق JSON الخاص بنا لطباعة والتحقق من حمولات JSON بسرعة.