تحقق من طلبات Authevo webhook عبر توقيع HMAC

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

ترويسة التوقيع

يحمل كل طلب X-Authevo-Signature: sha256=<hex>، حيث القيمة الست عشرية هي HMAC-SHA256 لجسم الطلب الخام تمامًا، مُوقَّعة بمفتاح الـ webhook السري لديك. ويظهر ذلك المفتاح مرة واحدة عند التسجيل، ويمكن تدويره من لوحة التحكم في أي وقت.

تحقق منه بأسطر قليلة

في نقطتك، اقرأ جسم الطلب الخام (البايتات نفسها قبل أي إعادة تحليل لـJSON)، واحسب HMAC ذاته بمفتاحك، وقارنه بالترويسة في زمن ثابت. في Node.js يكون ذلك const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex"); — ثم crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(header)). وإن لم يتطابقا، ارفض الطلب بـ401.

بعض القواعد العملية

• قارِن دائمًا في زمن ثابت (timingSafeEqual) لا بـ=== — فذلك يمنع تسريب التوقيع عبر التوقيت.
• جزّئ بايتات الجسم الخام لا كائنًا مُعاد تسلسله — فإعادة تحويل JSON قد تعيد ترتيب المفاتيح وتُفسد التطابق.
• دوّر المفتاح السري من لوحة التحكم إن انكشف يومًا؛ فيستخدم التحقق المفتاح الجديد فورًا.

وبمجرد اجتياز الطلب للفحص، تفرّع بناءً على الحدث — يخبرك otp.status_update بحالة تسليم رمز، ويكون account.low_balance إشارتك لإضافة رصيد قبل توقّف الإرسال. وتجاهل أي طلب يفشل في فحص التوقيع.