شرح Webhooks: الحمولات الموقعة وإعادة المحاولة للتكاملات الموثوقة
لقد قمت للتو ببناء نقطة نهاية لتلقي webhooks من مزود خدمة الدفع. يعمل الاختبار الأول بشكل جيد، ولكن في الإنتاج تلاحظ أحداثًا مفقودة، ورسومًا مكررة، ولا توجد طريقة لمعرفة ما إذا كان الطلب حقيقيًا. إن webhooks بسيطة من حيث المفهوم ولكنها صعبة التنفيذ بشكل صحيح. يشرح هذا الدليل كيفية تأمين webhooks باستخدام الحمولات الموقعة وتنفيذ منطق إعادة محاولة قوي حتى لا تتعطل تكاملاتك بصمت.
ما هي Webhooks ولماذا هي مهمة
Webhooks هي عمليات استدعاء HTTP محددة من قبل المستخدم يتم تشغيلها بواسطة الأحداث. بدلاً من أن يقوم تطبيقك بالاستعلام عن واجهة برمجة التطبيقات (API) بحثًا عن التغييرات، تقوم الخدمة بدفع البيانات إلى نقطة النهاية الخاصة بك عند حدوث شيء ما. وهذا يجعل التكاملات فعالة وشبه فورية.
تشمل حالات الاستخدام الشائعة إشعارات الدفع (مثل Stripe)، ومحفزات CI/CD (مثل GitHub)، ومنصات المراسلة (مثل Slack). ولكن مع نموذج الدفع هذا، تفقد السيطرة على وقت وصول الطلبات. لهذا السبب تحتاج إلى معالجة الأمان والموثوقية بشكل صريح.
المشكلة الأمنية: Webhooks غير الموقعة خطيرة
webhook غير موقّع هو مجرد طلب HTTP POST إلى عنوان URL عام. يمكن لأي شخص إرسال طلب يبدو وكأنه جاء من مزود الدفع الخاص بك. بدون التحقق، يمكن للمهاجمين تزوير الأحداث، مما يؤدي إلى طلبات احتيالية أو تسريب بيانات أو إجراءات غير مصرح بها.
الحل هو توقيع الحمولة. يقوم المرسل بحساب توقيع تشفيري على جسم الطلب باستخدام سر مشترك، ويضمّنه في رأس الطلب. تقوم نقطة النهاية الخاصة بك بإعادة حساب التوقيع ومقارنته. إذا تطابقا، فأنت تعلم أن الطلب أصلي ولم يتم العبث به.
كيفية توقيع حمولات Webhook باستخدام HMAC
HMAC (رمز المصادقة القائم على التجزئة) هو المعيار لتوقيع webhook. ويستخدم مفتاحًا سريًا ودالة تجزئة (مثل SHA-256) لإنتاج توقيع فريد للحمولة والسر.
إليك كيف يمكن للمرسل توقيع حمولة في بايثون:
import hmac
import hashlib
import json
secret = b'your_shared_secret'
payload = json.dumps({'event': 'payment.success', 'amount': 1000}).encode('utf-8')
signature = hmac.new(secret, payload, hashlib.sha256).hexdigest()
# Include signature in header: X-Signature:
على جانب الاستقبال، يجب عليك التحقق من التوقيع قبل معالجة الحمولة:
import hmac
import hashlib
def verify_signature(payload, received_signature, secret):
expected = hmac.new(secret, payload, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, received_signature)
هام: استخدم دائمًا دالة مقارنة ثابتة الوقت مثل hmac.compare_digest لمنع هجمات التوقيت. أيضًا، تحقق من التوقيع مقابل جسم الطلب الخام، وليس نسخة محللة، لأن تسلسل JSON يمكن أن يختلف.
أفضل الممارسات للحمولات الموقعة
- استخدم سرًا قويًا: قم بإنشاء سر عشوائي لا يقل عن 32 بايت وقم بتخزينه بشكل آمن (على سبيل المثال، متغير بيئة أو مدير أسرار).
- ضمّن طابعًا زمنيًا: أضف طابعًا زمنيًا إلى الحمولة الموقعة وارفض الطلبات الأقدم من بضع دقائق لمنع هجمات إعادة التشغيل.
- استخدم HTTPS: انقل webhooks دائمًا عبر TLS لحماية الحمولة والتوقيع أثناء النقل.
- قم بتدوير الأسرار بشكل دوري: دعم أسرار متعددة نشطة أثناء التدوير لتجنب التوقف.
التعامل مع حالات الفشل: إعادة المحاولة والتكافؤ
يمكن أن تفشل webhooks: قد يكون خادمك معطلاً، أو قد تنقطع الشبكة، أو قد تُرجع نقطة النهاية خطأً. سيقوم المرسل الموثوق بإعادة محاولة التسليم، ولكن يجب عليك تصميم المستقبل للتعامل مع التكرارات والأحداث غير المرتبة.
استراتيجيات إعادة المحاولة
يستخدم معظم مزودي webhook التراجع الأسي مع التذبذب. على سبيل المثال، أعد المحاولة بعد دقيقة واحدة، ثم 5 دقائق، ثم 30 دقيقة، حتى الحد الأقصى لعدد المحاولات. هذا يمنح نظامك وقتًا للتعافي دون إرهاقه.
إذا كنت تبني جانب المرسل، فقم بتنفيذ قائمة انتظار مع إعادة محاولات مجدولة. قم بتخزين الحمولة وعدد المحاولات، واستخدم عاملًا لمعالجة إعادة المحاولات.
التكافؤ: مفتاح إعادة المحاولة الآمنة
نظرًا لأن إعادة المحاولة يمكن أن تسبب تسليمًا مكررًا، يجب أن تكون نقطة النهاية الخاصة بك متكافئة. وهذا يعني أن معالجة نفس الحدث عدة مرات يجب أن يكون لها نفس تأثير معالجته مرة واحدة.
الأساليب الشائعة:
- استخدم معرف حدث فريد: قم بتضمين معرف في الحمولة وقم بتخزين المعرفات المعالجة في قاعدة بيانات. تجاهل الأحداث ذات المعرفات التي رأيتها بالفعل.
- صمم العمليات لتكون متكافئة: على سبيل المثال، استخدم upserts بدلاً من inserts، أو تحقق مما إذا كان المورد موجودًا بالفعل قبل إنشائه.
إليك فحص تكافؤ بسيط في بايثون:
def process_event(event_id, payload):
if db.exists('processed_events', event_id):
return # already processed
# process payload
db.insert('processed_events', event_id)
تأكد من أن الفحص والمعالجة يحدثان في معاملة واحدة لتجنب ظروف السباق.
مقارنة: الاستقصاء مقابل Webhooks
| الجانب | الاستقصاء | Webhooks |
|---|---|---|
| زمن الوصول | يعتمد على الفاصل الزمني (مثلاً 5 دقائق) | شبه فوري |
| حمل الخادم | طلبات مستمرة حتى عند عدم وجود تغييرات | طلبات فقط عند الأحداث |
| التعقيد | بسيط التنفيذ | يتطلب التوقيع، إعادة المحاولة، التكافؤ |
| الموثوقية | أنت تتحكم في إعادة المحاولة | يعتمد على سياسة إعادة المحاولة للمرسل |
خطوة بخطوة: تنفيذ مستقبل webhook آمن
- قم بإعداد نقطة نهاية HTTPS تقبل طلبات POST وتقرأ الجسم الخام.
- استخرج رأس التوقيع (مثل
X-Signature) ورأس الطابع الزمني إذا كان موجودًا. - تحقق من التوقيع باستخدام HMAC وسرك. ارفض إذا كان غير صالح.
- تحقق من الطابع الزمني لمنع هجمات إعادة التشغيل (مثلاً، ارفض إذا كان أقدم من 5 دقائق).
- حلل الحمولة واستخرج معرف الحدث.
- تحقق من التكافؤ بالبحث عن معرف الحدث في قاعدة البيانات الخاصة بك.
- عالج الحدث داخل معاملة تسجل أيضًا معرف الحدث.
- أعد حالة 2xx بسرعة لتأكيد الاستلام. إذا استغرقت المعالجة وقتًا، فضع المهمة في قائمة الانتظار وأعد 202 Accepted.
اختبار تنفيذ webhook الخاص بك
استخدم أدوات مثل ngrok لكشف خادمك المحلي ومحاكاة webhooks. اكتب اختبارات وحدة للتحقق من التوقيع، والتكافؤ، ومنطق إعادة المحاولة. على سبيل المثال، اختبر أن معرف الحدث المكرر يتم تجاهله وأن التوقيع غير الصالح يُرجع 401.
عند تصحيح الأخطاء، سجل الحمولة والتوقيع المستلمين (ولكن لا تسجل الأسرار أبدًا). إذا كنت تعمل مع حمولات JSON، فإن منسق JSON يمكن أن يساعدك في فحص والتحقق من البنية بسرعة.
الأسئلة الشائعة
ما هي حمولة webhook الموقعة؟
تتضمن الحمولة الموقعة توقيعًا تشفيريًا (عادة HMAC) يتم حسابه على جسم الطلب باستخدام سر مشترك. يتحقق المستقبل من التوقيع للتأكد من أن الطلب أصلي وغير معدل.
كم مرة يجب إعادة محاولة webhook؟
لا يوجد رقم عالمي، لكن الممارسة الشائعة هي 3-5 مرات إعادة محاولة مع التراجع الأسي. بعد ذلك، غالبًا ما يتم وضع علامة على الحدث على أنه فشل وقد يتطلب تدخلًا يدويًا أو قائمة انتظار للرسائل الميتة.
هل يمكنني استخدام webhooks بدون HTTPS؟
يجب عليك أبدًا استخدام webhooks عبر HTTP العادي. بدون TLS، يمكن للمهاجمين اعتراض الحمولة والتوقيع، وإعادة تشغيل الطلبات أو تعديلها. استخدم HTTPS دائمًا.
هل أنت مستعد لفحص وتنسيق حمولات webhook؟ جرب منسق JSON المجاني الخاص بنا للتحقق من بيانات JSON وتجميلها على الفور.