شرح Webhooks: الحمولات الموقعة وإعادة المحاولات الموثوقة
تقوم بنشر تكامل الدفع وكل شيء يعمل في بيئة الاختبار. ثم في الإنتاج يدفع العميل، وتنتهي مهلة نقطة النهاية الخاصة بك لمدة ثانيتين، ولا يتم تنشيط الطلب أبدًا. وفي الوقت نفسه، يعيد مزود الدفع محاولة نفس الحدث ثلاث مرات، ويُنشئ تطبيقك ثلاثة طلبات مكررة للطلب الذي نجح بالفعل. تبدو 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 على نص الطلب الخام باستخدام سر مشترك يعرفه فقط أنت والمزود. يحسب المزود التوقيع ويرسله في رأس؛ وتقوم أنت بإعادة حسابه ومقارنته.
التحقق من التوقيع بشكل صحيح
ثلاثة تفاصيل يسهل الخطأ فيها:
- استخدم النص الخام. قم بتحليل JSON فقط بعد التحقق. إعادة تسلسل كائن تم تحليله يغير المسافات البيضاء وترتيب المفاتيح، لذا لن يتطابق التوقيع أبدًا.
- قارن في وقت ثابت. مقارنة السلاسل الساذجة تكشف معلومات التوقيت. استخدم دالة آمنة زمنيًا.
- ضمّن الطابع الزمني في السلسلة الموقعة. توقيع
timestamp.bodyيسمح لك برفض الطلبات القديمة ويمنع هجمات إعادة التشغيل.
// 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. العمل الشاق — إرسال رسائل البريد الإلكتروني، استدعاء واجهات برمجة تطبيقات أخرى، إنشاء الفواتير — يجب أن يحدث في مهمة خلفية. إذا استغرق المعالجة وقتًا أطول من مهلة المزود، فسيتم اعتبار الطلب فاشلاً وإعادة المحاولة حتى لو قمت بالعمل.
- تحقق من التوقيع والطابع الزمني.
- أدخل الحدث في جدول بقيد فريد على معرف الحدث.
- أرجع
200فورًا. - عالج الحدث المخزن بشكل غير متزامن، مع وضع علامة مكتمل.
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 ودع إعادة المحاولة تقوم بعملها.
قائمة تحقق عملية للإنتاج
- استخدم HTTPS فقط؛ لا تقبل أبدًا webhooks عبر HTTP العادي.
- قم بتخزين سر التوقيع في مدير الأسرار الخاص بك ودعم التدوير — يسمح العديد من المزودين بسرين نشطين.
- سجل معرف الحدث والنوع ونتيجة التوقيع ونتيجة المعالجة لكل طلب.
- حدد نافذة تسامح (خمس دقائق عادة) لحظر إعادة التشغيل.
- اجعل المعالجات idempotent على مستوى قاعدة البيانات، وليس فقط في كود التطبيق.
- قم بتنبيه عند تجاوز معدل الفشل أو تأخر المعالجة لحد معين.
- وفر نقطة نهاية إعادة تشغيل يدوية لفريق الدعم.
اختبار webhooks محليًا
لا يمكنك بسهولة تلقي POST عام على localhost. الخيارات: أداة نفق تعرض منفذ التطوير الخاص بك، أو CLI المزود إذا كان لديه واحد، أو برنامج نصي صغير يرسل حمولة موقعة إلى المعالج الخاص بك حتى تتمكن من اختبار مسار التحقق.
أهم اختبار هو التكرار: أرسل نفس الحدث مرتين وتأكد من أن نظامك ينتهي في نفس الحالة. ثم أرسل حدثًا بطابع زمني قديم وتأكد من رفضه. ثم قم بالتلاعب ببايت واحد من النص وتأكد من فشل التحقق من التوقيع.
تصحيح الحمولات
نصوص webhook هي JSON، والحمولات المشوهة أو المتداخلة بعمق يصعب قراءتها في السجلات. يساعدك المنسق على فحص البنية بسرعة قبل كتابة كود التحليل. منسق JSON يعمل في المتصفح، لذا يمكنك لصق حمولة ملتقطة دون إرسال بيانات العملاء إلى خادم.
الأسئلة الشائعة
ما الفرق بين webhook و API؟
API قائم على السحب: يستدعي الكود الخاص بك المزود عندما يحتاج إلى بيانات. webhook قائم على الدفع: يستدعي المزود نقطة النهاية الخاصة بك عند حدوث حدث. تستخدم معظم التكاملات كليهما — webhooks لإشعارات الأحداث و API لجلب التفاصيل الكاملة أو تنفيذ الإجراءات.
لماذا لا يتطابق توقيع HMAC الخاص بي أبدًا؟
السبب المعتاد هو توقيع نص معاد تسلسله بدلاً من البايتات الخام. المسافات البيضاء وترتيب المفاتيح وهروب unicode كلها تغير التجزئة. اقرأ نص الطلب الخام قبل أي middleware JSON، وتأكد من تطابق السر وخوارزمية التجزئة مع وثائق المزود.
هل إعادة محاولات webhook مضمونة؟
لا. عادةً يعيد المزودون المحاولة لفترة محدودة مع تراجع أسي، ثم يستسلمون. تعامل مع webhooks كقناة إشعار سريعة بدلاً من مصدر حقيقة: قم بالتوفيق بشكل دوري مع API المزود حتى يتم تصحيح الأحداث الفائتة في النهاية.
إذا كنت تبني أو تصحح مستقبل webhook اليوم، فابدأ بتأمين التحقق من التوقيع والتخزين idempotent — هذان التغييران يقضيان على غالبية حوادث webhook في العالم الحقيقي.