Skip to main content
POST

نظرة عامة

توقّع Ayrshare كل تسليم webhook باستخدام HMAC-SHA256 لحمولة الطلب، مُفتاحًا بالمفتاح السري للتوقيع الخاص بك، حتى يتمكن المستقبل لديك من تأكيد أن التسليم صادر فعليًا من Ayrshare. راجع أمان Webhook لمعرفة كيفية عمل التحقق. يتيح لك تدوير المفتاح السري للتوقيع استبداله وفق جدول منتظم، أو فورًا إذا اشتبهت في أنه تعرض للكشف. لجعل التدوير آمنًا، تفتح Ayrshare نافذة سماح مدتها 24 ساعة بعد كل عملية تدوير، تُوقَّع خلالها التسليمات باستخدام كل من مفتاحك السري السابق ومفتاحك الجديد. يتيح لك هذا تحديث المستقبل الخاص بك وفق جدولك الخاص دون إسقاط أو رفض أي تسليم — وهو النمط ذاته المستخدم من قِبل Stripe وGitHub.
المفتاح السري للتوقيع يعمل على مستوى الملف الشخصي: هناك مفتاح سري واحد لكل User Profile (UID)، ويوقّع كل إجراء webhook مُسجَّل لهذا الملف الشخصي. لا يوجد مفتاح سري للتوقيع خاص بكل إجراء — تعيين المفتاح السري أو تدويره يغيّره لجميع الإجراءات على هذا الملف الشخصي دفعة واحدة.

التدوير من لوحة التحكم

يمكنك تعيين أو تدوير المفتاح السري للتوقيع من صفحة Webhooks في Developer Dashboard. تظهر لوحة Signing Secret فوق قائمة webhooks الخاصة بك بمجرد أن يمتلك الملف الشخصي webhook واحدًا مُسجَّلًا على الأقل.
1

افتح لوحة Signing Secret

انتقل إلى صفحة Webhooks. إذا لم يكن هناك مفتاح سري مُهيَّأ بعد، تعرض اللوحة No signing secret configured مع زر Set Signing Secret. إذا كان هناك مفتاح مُهيَّأ بالفعل، تعرض Signing secret configured مع زر Rotate.
2

تعيين أو تدوير

انقر على Set Signing Secret (للمرة الأولى) أو Rotate (لمفتاح سري موجود). ينفتح مربع حوار مع مفتاح سري قوي مولَّد عشوائيًا معبّأ مسبقًا ومكشوف. يمكنك Copy له، أو Regenerate واحدًا جديدًا، أو تبديل paste my own لتوفير قيمتك الخاصة.
3

أكّد

انسخ المفتاح السري في مكان آمن — يُعرض مرة واحدة فقط ولا يمكن استرجاعه من واجهة المستخدم أبدًا مرة أخرى — ثم أكّد للإرسال. تظهر رسالة نجاح وتُحدَّث اللوحة.
4

حدّث المستقبل الخاص بك

عند التدوير (وليس التعيين لأول مرة)، تعرض اللوحة مؤشر نافذة سماح نشطة ويكون زر Rotate معطلًا حتى تُغلَق النافذة. لديك 24 ساعة لنشر المفتاح السري الجديد إلى المستقبل الخاص بك.

التدوير عبر API

قم بتدوير (أو تعيين) المفتاح السري للتوقيع بمكالمة واحدة. يؤدي هذا إلى إنشاء مفتاح سري جديد، وإعادة توجيه مرجع المفتاح السري للملف الشخصي إليه، و — عندما يكون هناك مفتاح سري موجود — يسجّل المفتاح السري المُستبدَل كمفتاح سري سابق مع انتهاء صلاحية بعد 24 ساعة.

معاملات الترويسة

معاملات النص

string
مطلوب
قيمة المفتاح السري الجديد للتوقيع. يُقبل أي سلسلة نصية غير فارغة. نوصي بقيمة عشوائية طويلة وعالية الإنتروبيا (على سبيل المثال، 32 بايت عشوائية مُرمَّزة بـ base64url).
لا يُعاد المفتاح secret بنصه الصريح أبدًا في الاستجابة ولا يُسجَّل مطلقًا. تحمل الاستجابة refId الموجَّه للعميل (تجزئة لـ UID)، وليس UID ذاته أبدًا. ترويسة Profile-Key اختيارية وتُقصر التدوير على User Profile واحد للحسابات متعددة الملفات الشخصية. يُعيد الغياب أو الفراغ في secret خطأً معيّنًا (code: 101، “Missing/incorrect parameter”) مع حالة HTTP 400، ولا يُجرى أي تغيير على مفتاحك السري الحالي. يؤدي التعيين لأول مرة عبر API (بدون مفتاح سري موجود) إلى إنشاء المفتاح السري دون تسجيل مفتاح سري سابق ودون نافذة سماح.

إجراء التدوير الآمن

بفضل نافذة السماح التي مدتها 24 ساعة، لا يوجد ترتيب مطلوب للعمليات — يستمر المستقبل الخاص بك في العمل طوال الوقت. التسلسل الموصى به هو:
1

تدوير المفتاح السري

قم بالتدوير من لوحة التحكم أو عبر API. تبدأ Ayrshare فورًا في توقيع التسليمات باستخدام كل من مفتاحك السري السابق ومفتاحك الجديد.
2

حدّث المستقبل الخاص بك

خلال 24 ساعة، انشر المفتاح السري الجديد إلى مستقبل webhook الخاص بك حتى يتحقق مقابل القيمة الجديدة.
3

اترك النافذة تُغلق

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

التحقق من التوقيعات خلال نافذة السماح

خارج نافذة السماح، تحمل التسليمات الموقّعة الترويسات القياسية (راجع أمان Webhook):
خلال نافذة الـ 24 ساعة بعد التدوير، تُدرج ترويسة X-Authorization-Content-SHA256-V2 الجديدة كلا التوقيعين، الحالي أولًا، مفصولين بفاصلة:
X-Authorization-Content-SHA256 لم تتغير: تحمل دائمًا HMAC للمفتاح السري الحالي المفرد، للتوافق مع الإصدارات السابقة. لا تظهر التوقيعات المزدوجة إلا في ترويسة X-Authorization-Content-SHA256-V2 الجديدة.
يُسبق كل قيمة في X-Authorization-Content-SHA256-V2 بوسم مخطط. يشير v1= إلى توقيع HMAC-SHA256، مُحسَب تمامًا مثل X-Authorization-Content-SHA256. تكون ترويسة -V2 موجودة دائمًا كلما تم توقيع تسليم — إذ تحمل على الأقل v1=<current-sig> — لذا يمكنك الاعتماد عليها كعقد مستقبل مستقر. للتحقق من تسليم أثناء (أو خارج) عملية تدوير:
1

احسب HMAC

احسب HMAC-SHA256 لـ نص الطلب الخام باستخدام المفتاح السري للتوقيع المُهيَّأ محليًا لديك.
2

قارن مقابل كل توقيع مُدرج

اقرأ X-Authorization-Content-SHA256-V2، وقسّمها على الفواصل، وأزل بادئة v1= من كل قيمة، واقبل التسليم كأصلي إذا تطابق HMAC المحسوب لديك مع أي توقيع v1= مُدرج.
القبول عند تطابق أي توقيع مُدرج هو ما يجعل التدوير بدون توقف: المستقبل الذي لا يزال مُهيَّأً بالمفتاح السري القديم يتطابق مع v1=<previous-sig>، بينما المستقبل الذي جرى تحديثه إلى المفتاح السري الجديد يتطابق مع v1=<current-sig> — كلاهما ينجح طوال النافذة.

مثال على التحقق في المستقبل

Node.js
احسب دائمًا HMAC على بايتات نص الطلب الخام، تمامًا كما استُلمت — وليس على كائن JSON مُعاد التسلسل. قد تُغيّر إعادة التسلسل المسافات البيضاء أو ترتيب المفاتيح وتُبطل التحقق. استخدم مقارنة بزمن ثابت (مثل crypto.timingSafeEqual) لتجنب هجمات التوقيت.
إذا كان سجل المفتاح السري الحالي للتسليم مفقودًا، يمضي التسليم غير موقّع (بدون ترويسات توقيع) بدلًا من الفشل. إذا كان سجل المفتاح السري السابق فقط مفقودًا، يُتخطى التوقيع السابق ويُصدَر التوقيع الحالي مع ذلك في كلتا الترويستين.