كيفية استخدام محلّل توقيعات Webhook
- الصق جسم الطلب الخام كما استُلم بالضبط (دون إعادة تنسيق).
- اختر النظام، وأدخل السرّ، والصق قيمة ترويسة التوقيع.
- أضف الطابع الزمني للطلب في حالة Slack؛ وعنوان URL الكامل للطلب في حالة Twilio.
- اضغط «تحقق»: تُعرض النتيجة VALID/INVALID والتوقيع المتوقّع مقابل المقدَّم والملاحظات ومقتطف كود.
مزايا محلّل توقيعات Webhook
- يعيد حساب التوقيع المتوقّع محلياً باستخدام WebCrypto — لا تغادر الأسرار المتصفح أبداً
- HMAC-SHA256/SHA1/SHA512 عام (hex/Base64)، وStripe وGitHub وShopify وSlack وTwilio ورمز GitLab وSHA-256(body+secret)
- فحص هامش السماح الزمني لدى Stripe وSlack (الحماية من إعادة الإرسال)
- يعرض الحمولة الموقَّعة بالضبط ونتيجة المقارنة بزمن ثابت
- مقتطف تحقق جاهز للاستخدام بلغة Node.js للنظام المختار
مثال على محلّل توقيعات Webhook
ترويسة X-Hub-Signature-256 من GitHub
الإدخال:
Body {"a":1} · Secret s · Signature sha256=37beaf650f70b40ec9706929c2e9d835cbd63729988f48781e6383a147215f07النتيجة:
VALID — the signature matches
Algorithm: HMAC-SHA256 (hex) with "sha256=" prefix
Expected: sha256=37beaf65…215f07الأسئلة الشائعة حول محلّل توقيعات Webhook
ما الأنظمة المدعومة؟
HMAC-SHA256/SHA1/SHA512 عام بصيغة hex أو Base64، وStripe (t=…,v1=… مع هامش سماح زمني)، وGitHub (sha256=…)، وShopify (Base64)، وSlack (v0=… مع X-Slack-Request-Timestamp)، وTwilio (عنوان URL + المعاملات المرتّبة، SHA1 بصيغة Base64)، والرمز المشترك لدى GitLab، وSHA-256 للجسم + السرّ.
لماذا يظهر webhook صالح بنتيجة INVALID؟
في الغالب لأن الجسم أُعيد تسلسله: التنسيق أو تغيير ترتيب المفاتيح أو الأسطر الجديدة في النهاية تغيّر البايتات. الصق الجسم الخام بالضبط كما استلمه خادمك.
هل سرّي آمن؟
نعم — يُحسب HMAC باستخدام WebCrypto في متصفحك؛ ولا يغادر السرّ والحمولة الصفحة أبداً.
ما هامش السماح الزمني؟
في حالة Stripe وSlack، يجب أن يكون الطابع الزمني الموقَّع ضمن هامش السماح (5 دقائق افتراضياً) من الوقت الحالي، وإلا يُرفض التسليم المعاد إرساله حتى لو تطابق HMAC.
ملاحظات تقنية
يوقّع Stripe على "<t>.<body>" ويسرد توقيعات v1 في الترويسة؛ ويوقّع Slack على "v0:<timestamp>:<body>"؛ ويوقّع Twilio على عنوان URL الكامل متبوعاً بمعاملات POST مرتّبة حسب الاسم. وتجري المقارنات بزمن ثابت لمحاكاة كود التحقق في بيئة الإنتاج.