سر توقيع webhook من بيانات الدخول، وليس تفصيلًا عابرًا في الإعداد. أرسله كما ترسل كلمة المرور: تأكد ممن سيستلمه، وسلّمه عبر قناة لا تحتفظ بنسخ منه، واحرص على أن يستقر في مخزن للأسرار لا في تذكرة دعم. والخلاصة: أرسل رابطًا سريًا لمرة واحدة إلى جهة اتصال تحققت منها، وأرسل تعليمات الإعداد منفصلة.
ويتناول باقي الدليل اختيار القناة، وما تتحقق منه قبل الإرسال، وما يفعله العميل بالقيمة، ثم التدوير واستكشاف الأخطاء وإصلاحها دون أن تلصق السر مرة أخرى.
أي قناة تنقل السر؟
اختر القناة باختبارين: هل تستطيع التأكد ممن يمكنه فتحها؟ وكم نسخة تترك وراءها؟ يفشل البريد الإلكتروني والدردشة في الاختبار الثاني، لأن كل رسالة تُحفظ وتُزامَن وتُصدَّر بعد انتهاء التسليم بوقت طويل.
| الطريقة | ما تقدمه لك | ما تتحقق منه قبل الإرسال |
|---|---|---|
| بوابة عملاء تتطلب تسجيل الدخول | وصول لمستخدم محدد بالاسم يمكنك إبطاله | أن الحساب يخص جهة الاتصال الصحيحة |
| رابط سري لمرة واحدة | يُحذف نهائيًا بعد فتحه مرة واحدة، ولا يبقى شيء في الرسالة | العنوان الذي ترسله إليه، بتحقق منفصل |
| المراسلة المشفرة | حماية أثناء النقل | من غيره يستطيع فتح تلك المحادثة |
بوابة العملاء بحسابات دخول فردية خيار أول جيد إن كانت متاحة. امنح الوصول لشخص محدد بالاسم، لا لسلسلة رسائل مشتركة في المشروع، وأزله بعد اكتمال التسليم.
الرابط لمرة واحدة يُبقي بيانات الدخول خارج رسالة البريد أو الدردشة التي تنسق بها. في LinkPilot يُشفَّر السر في متصفحك قبل تخزينه، وتُحذف النسخة المخزنة نهائيًا بعد فتحها مرة واحدة، ويمكنك ضبط انتهاء صلاحية الرابط بعد ساعة أو يوم أو أسبوع. وتضيف خطط Pro عبارة مرور ترسلها عبر قناة منفصلة. تحدّ هذه الضوابط من مخاطر التسليم، لكنها لا تغني عن التحقق من أن الشخص الصحيح على الطرف الآخر.
المراسلة المشفرة بديل تلجأ إليه حين لا يكون أي من الخيارين السابقين عمليًا. فالتشفير أثناء النقل لا يصلح رسالة أُرسلت إلى عنوان خاطئ أو مجموعة تضم أكثر مما ينبغي، ولذلك يصبح التحقق من المستلم أهم.
وأيًا كان اختيارك، اقصر البريد الإلكتروني والدردشة بالنص العادي على التنسيق وحده. فحتى الخدمات التي تشفر الرسائل أثناء النقل تُبقي الاحتفاظ بها والنسخ الاحتياطية والوصول إلى الحسابات خارج سيطرتك.
التحقق من العميل والمستلم
لا تنفع القناة الآمنة شيئًا إذا وصل السر إلى صندوق الوارد الخطأ. قبل الإرسال، تأكد من أن من يطلبه مسؤول عن التكامل، ومن أن الطريق الذي تنوي استخدامه يخصه فعلًا.
- تأكد من الهوية عبر سجل معروف. استخدم جهة اتصال موثوقة أو علاقة عمل قائمة أو الإجراء المعتاد لدى العميل. وإذا كان الطلب من شخص جديد، أو تغيرت جهة الاتصال فجأة، أو بدا الاستعجال غير معتاد، فالأمر يستحق تحققًا مستقلًا.
- اقرأ العنوان حرفًا حرفًا، خاصة حين تنسخه من تذكرة أو رسالة حديثة، ففي الأسماء المتشابهة وصناديق البريد المشتركة تقع الأخطاء.
- راجع من يملك حق الوصول أيضًا. قبل المشاركة عبر بوابة أو مساحة عمل، اطّلع على قائمة أعضائها واستبعد كل من لا يحتاج إلى بيانات الدخول.
- تأكد من الاستلام عبر قناة ثانية. إذا أرسلت الرابط بالبريد الإلكتروني، فاسأل عبر رقم هاتف معروف أو قناة المشروع المعتادة إن كان الوصول قد نجح. ولا تضع السر في تلك الرسالة.
شارك السر مع الشخص الوحيد الذي سيضبط نقطة النهاية، ودعه يضعه في مخزن أسرار العميل. وإذا احتاج إليه عدة مهندسين، فضوابط الوصول في ذلك المخزن هي المكان المناسب لإدارة من يراه، لا نسخ منفصلة لكل واحد منهم.
تجهيز السر قبل التسليم
حدد لمن تعود بيانات الدخول، وأين يحفظها العميل، وكم تبقى نافذة التسليم مفتوحة. فهذا التجهيز يجعل التدوير واستكشاف الأخطاء لاحقًا أقل إرباكًا بكثير.
- سر واحد لكل عميل أو نقطة نهاية. إعادة استخدام السر تعني أن تسريبًا واحدًا يطال كل تكامل يشترك في القيمة نفسها، وأن تدويره لعميل واحد يعطل التكاملات كلها. احتفظ بسجل داخلي لنقطة النهاية التي يعود إليها كل سر، دون تكرار القيمة في ملاحظات المشروع.
- احفظ نسختك في مدير أسرار. لا في ملف نصي محلي ولا في تذكرة ولا في مستند مشترك. والانضباط نفسه ينطبق على مشاركة مفاتيح API: قيّد من يستطيع الوصول إلى بيانات الدخول، واجعل التسليم قصير العمر.
- حدد نافذة للاستلام. امنح العميل وقتًا يكفي لاستلام القيمة وإنهاء الإعداد، ولا أكثر. الرابط الذي يُحذف نهائيًا بعد فتحه مرة واحدة وتنتهي صلاحيته خلال يوم يغطي معظم حالات التسليم، وإذا انقضت النافذة فأنشئ رابطًا جديدًا بدل إعادة فتح القديم.
- أرسل تعليمات الإعداد منفصلة. عنوان URL لنقطة النهاية وترويسة التوقيع وخطوات التحقق مكانها وثائق العميل أو قناة المشروع. وفصلها عن السر يعني أن من ينسخ صفحة التعليمات لا ينسخ بيانات الدخول معها.
مساعدة العميل على حفظ السر واستخدامه بأمان
لا ينتهي التسليم حين يستطيع العميل قراءة القيمة، بل حين يستطيع الخادم قراءتها بأمان ويستخدمها للتحقق من التواقيع الواردة.
- احفظه في مدير أسرار أو متغير بيئة محمي تستطيع عملية الخادم قراءته، مع قصر الوصول على التطبيق والأشخاص الذين يشغّلونه.
- أبقه خارج الشيفرة المصدرية والسجلات وحمولات webhook. يُستخدم السر لحساب التوقيع أو التحقق منه، ولا ينتقل أبدًا في جسم الطلب، ولا ينبغي أن يظهر في مخرجات التصحيح أو المستودعات أو تذاكر الدعم. وتحقق مما تلتقطه أدوات النشر لديك قبل تفعيل التشخيص المفصل.
- تحقق من التواقيع على الخادم. يعيد المستقبِل حساب التوقيع على جسم الطلب الخام بالسر المشترك، ويقارنه بالترويسة التي وضعها المرسل. يثبت التوقيع أن الطلب أصلي ولم يُعدَّل، لكنه لا يشفر الحمولة. ويشرح دليل HackerOne عن توقيع webhooks لماذا يهم الجسم الخام والسر الصحيح كلاهما.
- شغّل حدثًا تجريبيًا. اطلب من العميل أن يتأكد من قبول توقيع صحيح ورفض توقيع أُفسد عمدًا. فهذا الاختبار يلتقط الأخطاء المعتادة: سر نقطة نهاية أخرى، أو جسم حُلّل قبل التحقق. وافصل بيانات دخول الاختبار عن بيانات الإنتاج حيث يدعم التكامل ذلك.
تقليل المخاطر بعد التسليم
ينبغي أن يترك التسليم سجلًا يمكن الرجوع إليه، لا أثرًا من النسخ الإضافية.
- سجّل من أُذن له ومتى. دوّن المستلم ونقطة النهاية أو العميل ووقت التسليم، ولا تدوّن القيمة أبدًا. وإذا لم تستطع معرفة إن كان الرابط قد فُتح أو من كان يستطيع الوصول إلى مجلد مشترك، فاعتبر ذلك سببًا لتشديد الإجراء في المرة القادمة.
- دوّر السر عند أي شبهة تسريب. السر الذي لُصق في تذكرة أو أُرسل إلى عنوان خاطئ أو وُجد في سجل لم يعد خاصًا. أنشئ بديلًا، وحدّث نقطة النهاية، وأبطل القيمة القديمة. حذف رابط المشاركة لا يمحو التسريب، والتدوير وحده يفعل ذلك.
- اتفق على إجراء التدوير من الآن. حدد من يطلب البديل ومن ينشئه ومن يثبّته، وهل يدعم التنفيذ فترة تداخل قصيرة، وكيف ستختبر القيمة الجديدة قبل إيقاف القديمة. فالإجراء المعروف مسبقًا أفضل من تبادل مستعجل أثناء انقطاع الخدمة.
- نظّف ما تبقى. بعد أن يؤكد العميل الاستلام، أبطل الوصول المؤقت واحذف النسخ المتناثرة في المسودات والتذاكر والملاحظات. وراجع قواعد الاحتفاظ في كل نظام معني، فحذف رسالة من واجهة واحدة نادرًا ما يزيلها من النسخ الاحتياطية.
استكشاف الأخطاء دون تسريب السر
مشكلة التسليم ليست مبررًا لإعادة إرسال بيانات الدخول عبر قناة أضعف. حدد أولًا أي الأمور الثلاثة هو الخلل: العميل لا يستطيع استلام السر، أو لا يستطيع ضبط نقطة النهاية، أو تصله الطلبات لكنه لا يستطيع التحقق من تواقيعها.
- فشل الاستلام أو انقضت النافذة. تحقق من المستلم مرة أخرى وأجرِ تسليمًا مضبوطًا جديدًا. لا تلصق القيمة في تذكرة، ولا تطلب من العميل أن يعيد إليك قيمته للمقارنة.
- عدم تطابق التوقيع. يكاد يكون دائمًا خللًا في مدخلات التحقق: سر لا يخص نقطة النهاية تلك، أو جسم أُعيد تنسيقه قبل حساب التجزئة، أو ترويسة قُرئت خطأ. اطلب من العميل الاختبار بحدث معروف عبر أدوات الاختبار لدى المرسل.
- الطلبات لا تصل أبدًا. هذه مشكلة في إيصال الطلبات أو توجيهها، لا في بيانات الدخول. راجع الطوابع الزمنية ورموز الاستجابة واختيار نقطة النهاية قبل أن يفكر أحد في التدوير. وتقدّم وثائق webhooks لدى Stripe نموذجًا مفيدًا للفصل بين تسجيل نقطة النهاية وإيصال الأحداث من جهة، والتحقق من التوقيع من جهة أخرى.
- شارك بيانات تشخيص منقّحة. يكفي معرّف الحدث والطابع الزمني ونقطة النهاية وفئة الخطأ. احذف السر، والتوقيع الكامل حين يكون حساسًا، وحقول الحمولة الخاصة، وراجع التنقيح قبل إرسال طلب نموذجي.
تحقق من المستلم، وسلّم السر مرة واحدة عبر قناة تنساه، وتأكد من أنه يستقر في مخزن للأسرار، ودوّره دون تردد إن احتمل أنه تسرب. وللاطلاع على النمط الأوسع لاستخدام الروابط لمرة واحدة في سير عمل المهندسين، راجع مشاركة الروابط الآمنة للمطورين.