يحتاج كل webhook للمدفوعات إلى ثلاث ضمانات: الأصالة (الطلب جاء فعلاً منا)، التسليم at-least-once (لا أحداث تُفقد بصمت) وعدم التكرار (إعادة التسليم لا تضاعف الشحن في قاعدة بياناتك).
الأصالة: يرسل كل webhook من Baynoy رأس X-Baynoy-Signature — sha256(timestamp + '.' + body) بسر نقطة النهاية الخاصة بك. ارفض إذا كان الطابع الزمني أقدم من 5 دقائق (دفاع replay) أو إذا لم يتطابق التوقيع في مقارنة وقت ثابت. نتبع نفس التنسيق الذي تستخدمه Stripe، لذا فإن middleware التحقق من Stripe الموجود يعمل دون تعديل.
At-least-once: نعيد المحاولة بـ exponential backoff عند 1د، 5د، 30د، 2س، 12س، 24س — بحد أقصى ست محاولات. كل محاولة تكتب سطراً في baynoy_webhook_deliveries مع حالة الاستجابة. زر replay-from-UI في لوحة القيادة يضرب نفس خط أنابيب التسليم؛ لا مسار خاص.
عدم التكرار: كل حدث يحمل event.id (UUIDv7 — قابل للفرز، متزايد رتيب). احفظه عند الاستلام الأول وارفض المكررات على مستوى قاعدة البيانات بقيد فريد. سنعيد التسليم. القيد هو شبكة الأمان الخاصة بك.
ثلاثة أسطر من middleware ولديك معالج webhook ينجو من انقطاع لمدة 6 ساعات دون فقدان إشعار دفع واحد.