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

Backend2026-11-15TryQuickToolBox

لماذا تفشل Webhooks في الإنتاج

لقد أنشأت نقطة نهاية webhook واختبرتها محليًا، وكل شيء يعمل. ثم يأتي الإنتاج: يرسل المزود حدثًا مكررًا، أو تنتهي مهلة نقطة النهاية الخاصة بك، أو ينتحل مهاجم طلبًا. فجأة، يصبح تكاملك غير موثوق وغير آمن.

Webhooks بسيطة من حيث المفهوم—استدعاءات HTTP يتم تشغيلها بواسطة الأحداث—لكن التطبيقات الجاهزة للإنتاج تتطلب معالجة دقيقة للأمان والموثوقية. يغطي هذا الدليل جانبين حاسمين: الحمولات الموقعة للتحقق من الأصالة واستراتيجيات إعادة المحاولة للتعامل مع الفشل.

ما هي Webhooks؟

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

لكن webhooks تقدم تحديات:

لنتناول الأمان أولاً.

تأمين Webhooks باستخدام الحمولات الموقعة

تستخدم الحمولات الموقعة سرًا مشتركًا لإنشاء توقيع تشفيري لنص الطلب. يضمّن المرسل هذا التوقيع في رأس (مثل X-Signature). تعيد نقطة النهاية الخاصة بك حساب التوقيع وتقارنه. إذا تطابقا، فإن الطلب أصلي.

كيف يعمل توقيع HMAC

يستخدم معظم المزودين HMAC-SHA256. يتم حساب التوقيع على نص الطلب الخام باستخدام السر المشترك. إليك التدفق:

  1. يشترك المزود والمستهلك في مفتاح سري.
  2. ينشئ المزود الحمولة، ويحسب HMAC-SHA256(secret, payload)، ويرسله في رأس.
  3. يستقبل المستهلك الطلب، ويقرأ النص الخام، ويحسب نفس 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 لمنع هجمات التوقيت.

اعتبارات أمان أخرى

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

حتى مع نقطة نهاية آمنة، يمكن أن تتسبب مشكلات الشبكة أو الأعطال المؤقتة في فشل تسليم webhook. تضمن آلية إعادة المحاولة القوية عدم فقدان الأحداث.

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

إذا كنت تبني مرسل webhook، فقم بتنفيذ التراجع الأسي مع التذبذب. على سبيل المثال:

أضف تذبذبًا عشوائيًا لتجنب مشاكل القطيع المتدافع. توقف بعد عدد أقصى من المحاولات وقم بالتنبيه.

أفضل الممارسات من جانب المستقبل

بصفتك مستهلك webhook، لا يمكنك التحكم في سياسة إعادة المحاولة الخاصة بالمرسل، لكن يمكنك جعل نقطة النهاية الخاصة بك مرنة:

التعامل مع التكرارات باستخدام الثبات

غالبًا ما يعيد مزودو webhook المحاولة عند انتهاء المهلة، لذا قد تتلقى نفس الحدث عدة مرات. اجعل المعالجة الخاصة بك ثابتة:

مثال باستخدام فهرس فريد في قاعدة البيانات:

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 الخاصة بك قوية وجاهزة للإنتاج.