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

Backend2026-11-11TryQuickToolBox

تقوم بنشر تكامل الدفع وكل شيء يعمل في بيئة الاختبار. ثم في الإنتاج يدفع العميل، وتنتهي مهلة نقطة النهاية الخاصة بك لمدة ثانيتين، ولا يتم تنشيط الطلب أبدًا. وفي الوقت نفسه، يعيد مزود الدفع محاولة نفس الحدث ثلاث مرات، ويُنشئ تطبيقك ثلاثة طلبات مكررة للطلب الذي نجح بالفعل. تبدو webhooks بسيطة — مجرد طلب HTTP POST — لكن الأجزاء الصعبة هي الثقة وضمانات التسليم.

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

ما هو webhook فعليًا

webhook هو استدعاء API معاكس. بدلاً من أن يقوم خادمك بالاستقصاء (polling) من المزود كل دقيقة سائلاً "هل هناك جديد؟"، يدفع المزود طلب HTTP إلى عنوان URL قمت بتسجيله عند حدوث حدث. تكون الحمولة عادة JSON، ويكون نوع الحدث إما في النص أو في رأس (header).

POST /webhooks/payments HTTP/1.1
Host: api.example.com
Content-Type: application/json
X-Event-Id: evt_8f2c1a
X-Timestamp: 1735689600
X-Signature: t=1735689600,v1=5d41402abc4b2a76b9719d911017c592

{
  "id": "evt_8f2c1a",
  "type": "payment.succeeded",
  "created": 1735689600,
  "data": { "order_id": "ord_123", "amount": 4999, "currency": "USD" }
}

هناك قراران تصميميان مهمان على جانب المرسل ويجب التحقق من كليهما عند تقييم أي مزود: هل يوقع الحمولة؟ وهل يعيد المحاولة عند الفشل؟

لماذا تعتبر webhooks غير الموقعة خطرة

عنوان URL الخاص بـ webhook الخاص بك عام. أي شخص يعرفه يمكنه إرسال حدث payment.succeeded مزيف وتعليم طلب غير مدفوع كمدفوع. قائمة IP المسموح بها تساعد قليلاً، لكن المزودين يغيرون عناوين IP، ويعملون خلف شبكات CDN، وقد لا تحصل على قائمة ثابتة.

الحل القوي هو توقيع HMAC على نص الطلب الخام باستخدام سر مشترك يعرفه فقط أنت والمزود. يحسب المزود التوقيع ويرسله في رأس؛ وتقوم أنت بإعادة حسابه ومقارنته.

التحقق من التوقيع بشكل صحيح

ثلاثة تفاصيل يسهل الخطأ فيها:

// Node.js / Express example
const crypto = require('crypto');

function verifySignature(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(
    header.split(',').map(p => p.split('='))
  );
  const timestamp = Number(parts.t);
  if (!timestamp) return false;

  // Reject stale requests (replay protection)
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - timestamp) > toleranceSeconds) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`)
    .digest('hex');

  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1 || '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

app.post('/webhooks/payments', express.raw({ type: '*/*' }), (req, res) => {
  if (!verifySignature(req.body.toString(), req.get('X-Signature'), SECRET)) {
    return res.status(401).send('invalid signature');
  }
  const event = JSON.parse(req.body.toString());
  // ... handle event
  res.status(200).send('ok');
});

لاحظ middleware express.raw(). إذا قمت بتركيب express.json() قبل هذا المسار، فسيتم تحليل النص بالفعل ويفشل التحقق من التوقيع بصمت — وهو خطأ شائع جدًا.

تصميم إعادة المحاولات التي لا تفقد الأحداث

تسليم webhook هو على الأقل مرة واحدة (at-least-once)، وليس بالضبط مرة واحدة (exactly-once). تفشل الشبكات، ويعيد نشرك تشغيل حاوية، وليس لدى المزود أي فكرة عما إذا كانت استجابة 200 الخاصة بك حقيقية. لذا يعيد المزود المحاولة بتراجع أسي (exponential backoff)، غالبًا لساعات أو أيام.

استجب بسرعة، وعالج لاحقًا

يجب أن تفعل نقطة النهاية الخاصة بك الحد الأدنى: التحقق، حفظ الحدث الخام، إرجاع 2xx. العمل الشاق — إرسال رسائل البريد الإلكتروني، استدعاء واجهات برمجة تطبيقات أخرى، إنشاء الفواتير — يجب أن يحدث في مهمة خلفية. إذا استغرق المعالجة وقتًا أطول من مهلة المزود، فسيتم اعتبار الطلب فاشلاً وإعادة المحاولة حتى لو قمت بالعمل.

  1. تحقق من التوقيع والطابع الزمني.
  2. أدخل الحدث في جدول بقيد فريد على معرف الحدث.
  3. أرجع 200 فورًا.
  4. عالج الحدث المخزن بشكل غير متزامن، مع وضع علامة مكتمل.

Idempotency: الحل الحقيقي للتكرارات

نظرًا لأن إعادة المحاولات تحدث، يجب أن يكون المعالج الخاص بك آمنًا للتشغيل مرتين. معرف الحدث هو مفتاح idempotency الطبيعي.

INSERT INTO webhook_events (event_id, type, payload, received_at)
VALUES ($1, $2, $3, now())
ON CONFLICT (event_id) DO NOTHING;

إذا أثر الإدراج على صفر صفوف، فقد رأيت هذا الحدث من قبل — أقر به وانتقل. بالنسبة لمنطق الأعمال، طبق نفس الفكرة: استخدم معرف الطلب كمفتاح فريد عند تنشيط الدفع، حتى لا يتمكن حدث ثانٍ من إنشاء تنشيط ثانٍ.

اختيار رموز الحالة بشكل متعمد

الحالةسلوك المزودمتى تستخدم
200 / 204وضع علامة تم التسليمتم قبول الحدث (حتى لو تمت معالجته بالفعل)
400عادة لا إعادة محاولةحمولة مشوهة لا يمكنك التعامل معها أبدًا
401عادة لا إعادة محاولةعدم تطابق التوقيع — تحقق من السر الخاص بك
429إعادة محاولة مع تراجعأنت تقوم بتحديد المعدل
500 / 503إعادة محاولة مع تراجعفشل مؤقت، قاعدة البيانات معطلة، النشر قيد التقدم

إرجاع 200 لحدث لم تتمكن من تخزينه هو أسوأ خيار: يتوقف المزود عن إعادة المحاولة ويضيع الحدث إلى الأبد. أرجع 5xx ودع إعادة المحاولة تقوم بعملها.

قائمة تحقق عملية للإنتاج

اختبار webhooks محليًا

لا يمكنك بسهولة تلقي POST عام على localhost. الخيارات: أداة نفق تعرض منفذ التطوير الخاص بك، أو CLI المزود إذا كان لديه واحد، أو برنامج نصي صغير يرسل حمولة موقعة إلى المعالج الخاص بك حتى تتمكن من اختبار مسار التحقق.

أهم اختبار هو التكرار: أرسل نفس الحدث مرتين وتأكد من أن نظامك ينتهي في نفس الحالة. ثم أرسل حدثًا بطابع زمني قديم وتأكد من رفضه. ثم قم بالتلاعب ببايت واحد من النص وتأكد من فشل التحقق من التوقيع.

تصحيح الحمولات

نصوص webhook هي JSON، والحمولات المشوهة أو المتداخلة بعمق يصعب قراءتها في السجلات. يساعدك المنسق على فحص البنية بسرعة قبل كتابة كود التحليل. منسق JSON يعمل في المتصفح، لذا يمكنك لصق حمولة ملتقطة دون إرسال بيانات العملاء إلى خادم.

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

ما الفرق بين webhook و API؟

API قائم على السحب: يستدعي الكود الخاص بك المزود عندما يحتاج إلى بيانات. webhook قائم على الدفع: يستدعي المزود نقطة النهاية الخاصة بك عند حدوث حدث. تستخدم معظم التكاملات كليهما — webhooks لإشعارات الأحداث و API لجلب التفاصيل الكاملة أو تنفيذ الإجراءات.

لماذا لا يتطابق توقيع HMAC الخاص بي أبدًا؟

السبب المعتاد هو توقيع نص معاد تسلسله بدلاً من البايتات الخام. المسافات البيضاء وترتيب المفاتيح وهروب unicode كلها تغير التجزئة. اقرأ نص الطلب الخام قبل أي middleware JSON، وتأكد من تطابق السر وخوارزمية التجزئة مع وثائق المزود.

هل إعادة محاولات webhook مضمونة؟

لا. عادةً يعيد المزودون المحاولة لفترة محدودة مع تراجع أسي، ثم يستسلمون. تعامل مع webhooks كقناة إشعار سريعة بدلاً من مصدر حقيقة: قم بالتوفيق بشكل دوري مع API المزود حتى يتم تصحيح الأحداث الفائتة في النهاية.

إذا كنت تبني أو تصحح مستقبل webhook اليوم، فابدأ بتأمين التحقق من التوقيع والتخزين idempotent — هذان التغييران يقضيان على غالبية حوادث webhook في العالم الحقيقي.