ForHosting KIT · أدوات المطورين

خطوات التحقق الآمن من توقيع webhook بنظام HMAC

أدخل خوارزمية HMAC مثل HMAC-SHA256 واسم الترويسة التي تحمل التوقيع، لتحصل على 8 خطوات مرتبة: حفظ الجسم الخام، وإعادة بناء الرسالة الموقّعة، والمقارنة في زمن ثابت، ثم فحص الحداثة والإعادة. مجانًا في متصفحك.

مجاني
يعمل في متصفحك
دون تسجيل
بياناتك لا تغادر جهازك

شغّل الأداة مجانًا اطّلع على الـAPI

استخدمها من الويبAPIالبريدTelegramالتطبيق قريبًا

تحوّل هذه الإمكانية خوارزمية HMAC واسم ترويسة المزوّد إلى قائمة دقيقة ومرتبة.

ما الذي يثبته توقيع HMAC

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

أخطاء شائعة ومتى تستخدم الخطوات

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

ابدأ بالبايتات التي وقّعها المزوّد

احتفظ ببايتات الطلب كما وصلت قبل أي تحليل. اقرأ الترويسة المحددة دون اعتبار لحالة أحرف اسمها، لكن تحقّق من قيمتها بصرامة. اتبع صياغة المزوّد الموثقة، وارفض القيم المفقودة أو الفارغة أو المكررة دون توقع أو المشوهة، واحفظ السر في مدير أسرار محمي.

أعد البناء واحسب وقارن بالترتيب الصحيح

أعد بناء الرسالة الموقعة بدقة؛ فقد تكون جسم الطلب الخام وحده، أو الوقت ثم فاصلاً والجسم. التزم بالترتيب والترميز الموثقين. احسب HMAC بالسر والخوارزمية الموحّدة، ثم رمّز الناتج كما يطلب المزوّد.

فك التوقيعين إلى مصفوفتين متساويتي الطول وقارنهما بزمن ثابت. يعني الترميز المشوه أو اختلاف الطول فشل التحقق.

اعتبر التشفير جزءاً من قرار القبول

يثبت تطابق HMAC معرفة السر، لكنه لا يثبت حداثة الرسالة أو عدم تكرارها. طبّق مهلة الوقت الموصى بها، واحفظ معرّفات الأحداث المقبولة واجعل المعالجة متكررة بأمان. بدّل الأسرار وفق فترة التداخل الموثقة.

ارفض الطلب قبل إدراجه للعمل وأعد خطأ عاماً وسجّل رموزاً آمنة فقط. اختبر الأجسام المعدلة والأوقات القديمة والترويسات المشوهة والأسرار الخاطئة وإعادة الأحداث.

حالات الاستخدام

مراجعة تكامل قائم

تحقّق من ترتيب التقاط الجسم وحساب HMAC والمقارنة الآمنة ومنع الإعادة.

إعداد خطة اختبار أمني

أنشئ اختبارات سلبية للترويسات المفقودة والأجسام المعدلة والتواقيع المشوهة والأوقات القديمة والإعادة.

الأسئلة الشائعة

ما الخوارزميات المعروفة؟

HMAC-SHA1 وHMAC-SHA256 وHMAC-SHA384 وHMAC-SHA512. وتؤدي أي خوارزمية أخرى إلى خطأ إدخال.

لماذا يجب الاحتفاظ بجسم الطلب الخام؟

لأن تحليله وإعادة تسلسله قد يغيران بايتاته ويُبطلان توقيعاً صحيحاً.

هل يمنع تطابق HMAC هجمات الإعادة؟

لا. تحقّق من الوقت الموقّع وأزل تكرار معرّفات الأحداث عندما يوفرها المزوّد.

لماذا تجب مقارنة التوقيع في زمن ثابت؟

لأن المقارنة العادية قد تكشف من خلال زمن الاستجابة مقدار ما تطابق من التوقيع. حوّل القيمتين إلى بايتات متساوية الطول واستخدم مقارنة آمنة زمنيًا، واعتبر أي اختلاف في الطول أو فك الترميز فشلًا في التحقق.

هل أحتاج إلى إدخال السر أو محتوى الرسالة المستلمة؟

لا. تحتاج قائمة الخطوات فقط إلى خوارزمية HMAC واسم ترويسة التوقيع، فيبقى السر والرسالة والتوقيع داخل نظام الاستقبال الخاص بك.

أدوات ذات صلة

للمطوّرين — الوصول عبر API

كل ما في هذه الصفحة متاح برمجيًا. هذا القسم موجّه للفرق التقنية التي تريد ربط الأداة بأنظمتها الخاصة؛ بقية المستخدمين يمكنهم استخدام الأداة أعلاه مباشرة دون الحاجة لقراءة ما يلي.

الـEndpoint

POSThttps://api.kit.forhosting.com/security/webhook-signature-verify-steps

صادِق على طلبك بترويسة Bearer، وأرسل طلب POST واحدًا لتدخل مهمتك قائمة التنفيذ فورًا؛ ثم تستلم النتيجة عبر webhook أو رابط موقّع.

استدعِ الخدمة من بيئتك

curl -X POST https://api.kit.forhosting.com/security/webhook-signature-verify-steps \
  -H "Authorization: Bearer $KIT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"algorithm":"HMAC-SHA256","header_name":"X-Webhook-Signature"}'

const res = await fetch("https://api.kit.forhosting.com/security/webhook-signature-verify-steps", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.KIT_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "algorithm": "HMAC-SHA256",
    "header_name": "X-Webhook-Signature"
  })
});
const { task_id } = await res.json();

import os, requests

res = requests.post(
    "https://api.kit.forhosting.com/security/webhook-signature-verify-steps",
    headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
    json={
    "algorithm": "HMAC-SHA256",
    "header_name": "X-Webhook-Signature"
},
)
task_id = res.json()["task_id"]

<?php
$res = file_get_contents("https://api.kit.forhosting.com/security/webhook-signature-verify-steps", false, stream_context_create([
  "http" => [
    "method"  => "POST",
    "header"  => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
    "content" => '{"algorithm":"HMAC-SHA256","header_name":"X-Webhook-Signature"}',
  ],
]));
$task = json_decode($res, true);

body := bytes.NewBufferString(`{"algorithm":"HMAC-SHA256","header_name":"X-Webhook-Signature"}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/security/webhook-signature-verify-steps", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)

مثال على الطلب

{
  "algorithm": "HMAC-SHA256",
  "header_name": "X-Webhook-Signature"
}

مثال على الاستجابة

{
  "task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
  "type": "security.webhook_signature_verify_steps",
  "status": "queued",
  "_links": {
    "result": "/tasks/tsk_…/result"
  }
}

الواجهة غير متزامنة: تستلم task_id فور الإرسال، ويمكنك الاستعلام عن الحالة بمعدل طلب واحد في الثانية.

الأسعار

لكل طلب$0.002

السعر معلن كما تراه: لا tokens ولا نظام نقاط؛ وإن فشلت المهمة فلن تُحاسَب عليها.

الأخطاء

HTTP	الرمز	المعنى
`401`	`unauthorized`	مفتاح الوصول مفقود أو غير صالح؛ تحقق من ترويسة Bearer في طلبك.
`402`	`insufficient_balance`	رصيدك لا يكفي لتنفيذ هذه المهمة؛ أعد شحن الرصيد ثم أعد المحاولة.
`404`	`unknown_type`	نوع المهمة المطلوب غير موجود في الكتالوج — راجع الاسم المرسل في الطلب.
`429`	`rate_limited`	تجاوزت الحد المسموح من الطلبات؛ انتظر قليلًا ثم أعد المحاولة.

ملاحظات تقنية

غالباً ما يفشل التحقق من توقيع webhook عند الحدود: فقد يغيّر إطار العمل جسم الطلب، أو تُحلّل الترويسة بتساهل، أو تكشف المقارنة العادية معلومات زمنية. ولا تحتاج إلى الحمولة أو السر أو التوقيع. استخدم النتيجة عند تنفيذ نقطة النهاية أو مراجعتها، ثم طابق تنسيق الوقت والترميز ومهلة منع الإعادة مع وثائق المزوّد الرسمية.

ابدأ بالبايتات التي وقّعها المزوّد

فقد تؤدي إعادة تسلسل JSON إلى تغيير المسافات والترتيب والمحارف المهروبة وUnicode ونهايات الأسطر.

حالات التكامل

تنفيذ نقطة نهاية webhook جديدة

حوّل خوارزمية المزوّد وترويسته إلى قائمة قابلة للمراجعة قبل كتابة الشفرة.

أسئلة تقنية

هل تتحقق هذه الأداة من webhook فعلي؟

لا. فهي تنتج خطوات التنفيذ ولا تطلب الحمولة أو السر أو التوقيع.

هل ينبغي إرسال سر webhook؟

لا. المطلوب فقط الخوارزمية واسم الترويسة؛ احتفظ بالسر في بيئتك المحمية.

ما تكلفة طلب API؟

يكلف كل طلب $0.002. ويمكن للتنفيذ الحتمي في المتصفح العمل دون إرسال أي أسرار.

اطّلع على توثيق KIT الكامل ←

شغّل الأداة مجانًا

ما الذي يثبته توقيع HMAC

أخطاء شائعة ومتى تستخدم الخطوات

ابدأ بالبايتات التي وقّعها المزوّد

أعد البناء واحسب وقارن بالترتيب الصحيح

اعتبر التشفير جزءاً من قرار القبول

حالات الاستخدام

مراجعة تكامل قائم

إعداد خطة اختبار أمني

الأسئلة الشائعة

أدوات ذات صلة

للمطوّرين — الوصول عبر API

الـEndpoint

استدعِ الخدمة من بيئتك

مثال على الطلب

مثال على الاستجابة

الأسعار

الأخطاء

ملاحظات تقنية

ابدأ بالبايتات التي وقّعها المزوّد

حالات التكامل

تنفيذ نقطة نهاية webhook جديدة

أسئلة تقنية

شكرًا