شرح Webhooks: الحمولات الموقعة وإعادة المحاولة
لقد قمت للتو بدمج خدمة طرف ثالث ترسل webhooks إلى نقطة النهاية الخاصة بك. كل شيء يعمل في الاختبار، ولكن في الإنتاج تلاحظ أحداثًا مفقودة، وتسليمات مكررة، ومخاوف أمنية عرضية. webhooks بسيطة من حيث المفهوم ولكنها صعبة في الممارسة العملية - خاصة عندما يتعلق الأمر بالتحقق من الأصالة والتعامل مع حالات الفشل.
يشرح هذا الدليل كيفية تأمين webhooks باستخدام الحمولات الموقعة وتنفيذ آليات إعادة محاولة قوية، حتى تتمكن من بناء تكاملات موثوقة.
ما هي Webhooks؟
webhooks هي عمليات استدعاء HTTP محددة من قبل المستخدم. عندما يحدث حدث في نظام المصدر (على سبيل المثال، اكتمال الدفع)، يرسل طلب HTTP POST إلى عنوان URL تحدده، يحتوي على بيانات حول الحدث. هذا يسمح بالتواصل في الوقت الفعلي بين الخدمات دون الحاجة إلى الاستقصاء.
لكن webhooks تقدم تحديات: كيف تعرف أن الطلب جاء بالفعل من المرسل المتوقع؟ ماذا لو كانت نقطة النهاية الخاصة بك معطلة مؤقتًا؟ هنا يأتي دور الحمولات الموقعة وإعادة المحاولة.
تأمين Webhooks باستخدام الحمولات الموقعة
تستخدم الحمولة الموقعة توقيعًا تشفيريًا لإثبات أن الطلب نشأ من المرسل ولم يتم العبث به. النهج الشائع هو HMAC (رمز مصادقة الرسائل القائم على التجزئة) باستخدام سر مشترك.
كيف تعمل توقيعات HMAC
يحسب المرسل HMAC على جسم الطلب (وأحيانًا رؤوس مثل الطابع الزمني) باستخدام مفتاح سري. يتم إرسال التوقيع في رأس (على سبيل المثال، X-Signature). يعيد خادمك حساب HMAC ويقارنه بالتوقيع المستلم. إذا تطابقا، فإن الطلب أصلي.
إليك مثالًا بسيطًا في Python باستخدام Flask:
import hmac
import hashlib
from flask import Flask, request, abort
app = Flask(__name__)
SECRET = b'your_shared_secret'
@app.route('/webhook', methods=['POST'])
def webhook():
signature = request.headers.get('X-Signature')
if not signature:
abort(400, 'Missing signature')
body = request.get_data()
expected = hmac.new(SECRET, body, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, signature):
abort(401, 'Invalid signature')
# Process the event
return '', 200
النقاط الرئيسية:
- استخدم دائمًا دالة مقارنة ثابتة الوقت (مثل
hmac.compare_digest) لمنع هجمات التوقيت. - قم بتضمين طابع زمني في البيانات الموقعة لمنع هجمات إعادة التشغيل؛ ارفض الطلبات الأقدم من بضع دقائق.
- احتفظ بالسر آمنًا - لا تعرضه أبدًا من جانب العميل.
تدابير أمنية إضافية
- HTTPS: استخدم دائمًا HTTPS لحماية الحمولة أثناء النقل.
- قائمة IP المسموح بها: إذا نشر المزود نطاقات IP، فقم بتقييد الطلبات لتلك العناوين.
- التماثل: استخدم معرفات الأحداث لإزالة التكرار، حيث قد تتسبب إعادة المحاولة في تكرارات.
تنفيذ إعادة المحاولة الموثوقة
يمكن أن يفشل مستهلكو webhooks: قد يكون خادمك معطلاً، أو قد تنتهي مهلة المعالجة. يجب على المرسلين إعادة محاولة التسليمات الفاشلة مع تأخير أسي. كمستهلك، يجب عليك التعامل مع إعادة المحاولة بسلاسة.
على جانب المرسل (إذا كنت تبني نظام webhooks)
- أعد 2xx بسرعة: أقر بالاستلام قبل المعالجة لتجنب المهلات. استخدم قائمة انتظار للعمل غير المتزامن.
- أعد المحاولة عند الفشل: إذا لم يتم استلام 2xx خلال مهلة (على سبيل المثال، 5 ثوانٍ)، أعد المحاولة بتأخيرات متزايدة (على سبيل المثال، 1 ثانية، 5 ثوانٍ، 30 ثانية، 5 دقائق، 30 دقيقة).
- حدد عدد المحاولات: بعد عدد أقصى من المحاولات (على سبيل المثال، 5)، ضع علامة على التسليم على أنه فاشل وقم بالتنبيه.
- قم بتضمين معرف حدث فريد: حتى يتمكن المستهلكون من إزالة التكرار.
على جانب المستهلك (نقطة النهاية الخاصة بك)
- استجب بسرعة: أعد 2xx فورًا وقم بالمعالجة بشكل غير متزامن إذا لزم الأمر.
- كن متماثلًا: استخدم معرف الحدث لتجنب معالجة نفس الحدث مرتين.
- تعامل مع التكرارات: قم بتخزين معرفات الأحداث المعالجة لفترة معقولة.
- سجل حالات الفشل: إذا فشلت المعالجة، أعد 5xx لتحفيز إعادة المحاولة، ولكن تأكد من عدم الوقوع في حلقة.
مقارنة: الحمولات الموقعة مقابل المصادقة الأساسية
| النهج | الأمان | التعقيد | حماية إعادة التشغيل |
|---|---|---|---|
| توقيع HMAC | عالي (سلامة + أصالة) | متوسط | نعم (مع طابع زمني) |
| المصادقة الأساسية | منخفض (بيانات الاعتماد في الرأس) | منخفض | لا |
| قائمة IP المسموح بها | متوسط (على مستوى الشبكة) | منخفض | لا |
اختبار Webhooks محليًا
أثناء التطوير، تحتاج إلى عنوان URL عام لتلقي webhooks. يمكن لأدوات مثل ngrok أو localtunnel كشف خادمك المحلي. اختبر دائمًا التحقق من التوقيع وسلوك إعادة المحاولة مع حالات فشل محاكاة.
عند فحص حمولات webhook، قد تحتاج إلى تنسيق JSON لسهولة القراءة. يمكن أن تساعدك أداة تنسيق JSON في طباعة جسم JSON بشكل جميل والتحقق من صحته.
الأسئلة الشائعة
ما هي حمولة webhook الموقعة؟
تتضمن الحمولة الموقعة توقيعًا تشفيريًا (غالبًا HMAC) يسمح للمستقبل بالتحقق من أصالة الطلب وسلامته.
كم مرة يجب إعادة محاولة webhook؟
لا يوجد عدد ثابت؛ تتراوح الممارسات الشائعة من 3 إلى 10 محاولات مع تأخير أسي. المفتاح هو موازنة الموثوقية مع استخدام الموارد والتنبيه عند الفشل المستمر.
هل يمكنني استخدام webhooks بدون توقيعات؟
لا ينصح بذلك. بدون توقيعات، لا يمكنك التحقق من المرسل، مما يجعل نقطة النهاية الخاصة بك عرضة للانتحال. استخدم دائمًا التوقيعات في الإنتاج.
هل أنت مستعد لتصحيح حمولات webhook الخاصة بك؟ جرب أداة تنسيق JSON للتحقق من بيانات JSON وتنسيقها بسرعة.