التحقق من توقيع webhook

التعريف

التحقق من توقيع webhook آلية تُستخدم لمصادقة مصدر حدث webhook. فعندما يرسل مزوّد مثل Resend أو SendGrid إشعارًا بحدث بريد إلكتروني، فإنه يضمّن تجزئة للحمولة موقَّعة بمفتاح سري. ويستخدم الخادم المستلِم المفتاح السري نفسه لإعادة حساب التجزئة ومقارنتها بالتوقيع المقدَّم في ترويسة الطلب.

آلية العملية

يولّد المزوّد تجزئة HMAC باستخدام سر مشترك ومتن الطلب. وتُرسل هذه التجزئة في ترويسة، تُسمى غالبًا X-Signature أو ما يشابهها. ويلتقط المستلِم متن الطلب الخام وترويسة التوقيع. ثم يحسب المستلِم تجزئة HMAC الخاصة به باستخدام السر المشترك. فإذا طابقت التجزئة المحسوبة قيمة الترويسة، فالطلب أصيل. وإذا اختلفتا، يُرفض الطلب بوصفه غير مخوَّل.

أهميته للمُرسِلين

دون التحقق، يستطيع أي كيان يعرف عنوان URL الخاص بـ webhook لديك إرسال بيانات مزيفة إلى خادمك. وقد يؤدي ذلك إلى تحديثات خاطئة في قاعدة البيانات، مثل وسم رسالة مسلَّمة بأنها مرتدة. ويمنع تطبيق التحقق هجمات الانتحال ويضمن أن يستجيب تطبيقك للأحداث الشرعية التي تطلقها بنية بريدك التحتية فقط.

ملاحظات تشغيلية

من الأخطاء الشائعة تحليل متن الطلب إلى كائن JSON قبل التحقق من التوقيع. فلأن محللات JSON قد تغيّر المسافات البيضاء أو ترتيب المفاتيح، قد لا تطابق السلسلة الناتجة الحمولة الأصلية التي استخدمها المزوّد. استخدم دائمًا متن الطلب الخام غير المحلَّل في حسابات HMAC لتجنب إخفاقات التحقق.

مثال على التنفيذ

في بيئة Node.js، يستخدم المطوّر الوحدة crypto لإنشاء تجزئة hmac sha256 لمتن الطلب الخام باستخدام سر المزوّد. ثم تُقارن هذه النتيجة بترويسة التوقيع باستخدام دالة مقارنة ثابتة الزمن لمنع هجمات التوقيت. وتوفّر SendHQ أدوات مجانية على https://sendhq.cc/tools للمساعدة في إدارة إعدادات البريد المختلفة التي تسبق غالبًا إعداد webhook.

أسئلة تطرحها الفرق

المصادر الأساسية

• وثائق Resend — Resend
• وثائق مطوري Postmark — Postmark
• وثائق SendGrid — Twilio SendGrid