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

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

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

● Betaمجاني · داخل متصفحك
استخدمها من الويبAPIالبريدTelegramالتطبيق قريبًا

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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"}'
{
  "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الرمزالمعنى
401unauthorizedمفتاح الوصول مفقود أو غير صالح؛ تحقق من ترويسة Bearer في طلبك.
402insufficient_balanceرصيدك لا يكفي لتنفيذ هذه المهمة؛ أعد شحن الرصيد ثم أعد المحاولة.
404unknown_typeنوع المهمة المطلوب غير موجود في الكتالوج — راجع الاسم المرسل في الطلب.
429rate_limitedتجاوزت الحد المسموح من الطلبات؛ انتظر قليلًا ثم أعد المحاولة.

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