محلّل توقيعات Webhook

تعمل في المتصفح اختبار واجهات API

الصق الحمولة وترويسة التوقيع والسرّ لإعادة حساب التوقيع المتوقّع وفق نظام المزوّد (بما في ذلك صيغ Stripe/Slack ذات الطوابع الزمنية) ومعرفة ما إذا كان مطابقاً. لا يغادر شيء متصفحك.

الخصوصية: تعمل هذه الأداة بالكامل في متصفحك. لا تغادر بياناتك جهازك أبداً.

ما هو HMAC؟

HMAC (رمز مصادقة الرسالة المعتمد على التجزئة) يجمع مفتاحاً سرياً مع دالة تجزئة مثل SHA-256 لإنتاج علامة تثبت أن الرسالة أنشأها من يملك المفتاح ولم تُعدَّل بعدها. هو ما يوقّع رموز JWT من نوع HS256 ومعظم حمولات webhook؛ والتحقق منه يعني إعادة حسابه بالمفتاح نفسه والمقارنة بزمن ثابت.

يعيد التحقق بناء التوقيع من البايتات الخام بالضبط ثم يقارنه بزمن ثابت؛ وبايت واحد متغيّر أو سرّ خاطئ أو طابع زمني قديم يعطي INVALID.
  1. 1جسم الطلب الخامالبايتات نفسها التي استلمها خادمك

    فرع: التنسيق أو تغيير ترتيب المفاتيح أو سطر جديد في النهاية يغيّر البايتاتفشل

  2. 2بناء الحمولة الموقَّعةالجسم في GitHub وShopify؛ و<t>.<body> في Stripe؛ وv0:<timestamp>:<body> في Slack؛ وعنوان URL الكامل متبوعاً بمعاملات POST مرتّبة حسب الاسم في Twilio
  3. 3HMAC بسرّكالخوارزمية SHA-256، وSHA-1 في Twilio؛ ويتيح HMAC العام أيضاً SHA-1 أو SHA-512
  4. 4ترميز الناتجالتوقيع المتوقّع: hex أو Base64؛ ويضيف GitHub البادئة sha256=، ويضيف Slack البادئة v0=
  5. 5مقارنة بزمن ثابتالمتوقّع مقابل قيمة ترويسة التوقيع؛ وفي Stripe كل قيمة v1

    فرع: لا تطابقفشل

    بوابة: في Stripe وSlack يجب أن يقع الطابع الزمني الموقَّع ضمن هامش السماح (5 دقائق افتراضياً)، وإلا فالنتيجة INVALID

  6. 6VALIDالتوقيع مطابقنجاح

الرمز المشترك لدى GitLab وSHA-256 للجسم + السرّ لا يمرّان بخطوة HMAC: يُقارَن الرمز كما هو، والآخر تجزئة عادية.

كيفية استخدام محلّل توقيعات Webhook

  1. الصق جسم الطلب الخام كما استُلم بالضبط (دون إعادة تنسيق).
  2. اختر النظام، وأدخل السرّ، والصق قيمة ترويسة التوقيع.
  3. أضف الطابع الزمني للطلب في حالة Slack؛ وعنوان URL الكامل للطلب في حالة Twilio.
  4. اضغط «تحقق»: تُعرض النتيجة 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 مرتّبة حسب الاسم. وتجري المقارنات بزمن ثابت لمحاكاة كود التحقق في بيئة الإنتاج.

المراجع