شرح Webhooks: الحمولات الموقعة وإعادة المحاولة

لقد قمت للتو بدمج webhook لمزود خدمة الدفع. تقول الوثائق: "سنقوم بإرسال طلب POST إلى نقطة النهاية الخاصة بك عند نجاح الدفع." بسيط، أليس كذلك؟ ثم لاحظت أحداثًا مكررة، وإشعارات مفقودة، وتنبيهًا أمنيًا حول طلبات مزيفة. webhooks بسيطة من حيث المفهوم ولكنها صعبة في الإنتاج. تشرح هذه المقالة كيفية تنفيذ webhooks بشكل صحيح باستخدام الحمولات الموقعة وإعادة المحاولة، حتى تتمكن من بناء تكاملات موثوقة وآمنة.

ما هي Webhooks؟

webhook هو API عكسي: بدلاً من أن يقوم تطبيقك بالاستقصاء (polling) عن التحديثات من خدمة ما، تقوم الخدمة بدفع الأحداث إلى نقطة النهاية الخاصة بك عبر HTTP POST. إنه فعال وشبه فوري. تشمل الاستخدامات الشائعة إشعارات الدفع، ومحفزات CI/CD، وتكاملات الدردشة.

لكن webhooks تقدم تحديات: كيف تعرف أن الطلب جاء بالفعل من المزود؟ ماذا لو كان الخادم الخاص بك معطلاً؟ ماذا لو وصل نفس الحدث مرتين؟ دعنا نتعامل مع هذه واحدة تلو الأخرى.

تأمين Webhooks باستخدام الحمولات الموقعة

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

كيف تعمل توقيعات 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 للمقارنة في وقت ثابت لمنع هجمات التوقيت. أيضًا، تحقق من التوقيع قبل تحليل جسم JSON لتجنب المعالجة غير الضرورية.

أفضل الممارسات للتوقيعات

• استخدم مفتاحًا سريًا قويًا: قم بإنشاء مفتاح عشوائي لا يقل عن 32 بايت وقم بتخزينه بشكل آمن (على سبيل المثال، متغير بيئة).
• قم بتضمين طابع زمني: لمنع هجمات إعادة التشغيل، غالبًا ما يقوم المزودون بتضمين طابع زمني في الحمولة الموقعة. ارفض الطلبات الأقدم من بضع دقائق.
• قم بتدوير المفاتيح السرية بشكل دوري: دعم مفاتيح سرية متعددة نشطة أثناء التدوير لتجنب التوقف.
• وثق خوارزمية التوقيع: حدد دالة التجزئة (SHA-256 هي المعيار) واسم الرأس.

التعامل مع الفشل بإعادة المحاولة

webhooks هي إطلاق النار والنسيان من منظور المزود، ولكن قد تكون نقطة النهاية الخاصة بك غير متاحة مؤقتًا. لضمان التسليم، ينفذ المزودون سياسات إعادة المحاولة. بصفتك متلقيًا، يجب أن تكون مستعدًا لإعادة المحاولة والتكرارات.

استراتيجيات إعادة المحاولة التي يستخدمها المزودون

يعيد معظم المزودين المحاولة باستخدام التراجع الأسي: على سبيل المثال، فورًا، ثم بعد دقيقة واحدة، 5 دقائق، 30 دقيقة، إلخ، حتى الحد الأقصى لعدد المحاولات (غالبًا 5-10). يسمح لك بعضهم أيضًا بتكوين جدول إعادة المحاولة. يختلف السلوك الدقيق، لذا اقرأ وثائق المزود.

تصميم نقطة النهاية الخاصة بك لإعادة المحاولة

يجب أن تقوم نقطة النهاية الخاصة بك بما يلي:

• الرد بسرعة: أقر بالاستلام بحالة 2xx في غضون ثوانٍ قليلة. قم بإجراء المعالجة الثقيلة بشكل غير متزامن (على سبيل المثال، ضع الحدث في قائمة الانتظار).
• كن متسقًا (idempotent): قد يتم تسليم نفس الحدث عدة مرات. استخدم مفتاح التنفيذ الموحد (غالبًا ما يتم توفيره في حمولة الحدث أو الرأس) لإزالة التكرار. قم بتخزين معرفات الأحداث المعالجة لفترة معقولة.
• أعد رموز الحالة المناسبة: 2xx للنجاح، 4xx لأخطاء العميل (قد لا يعيد المزود المحاولة)، 5xx لأخطاء الخادم (سيعيد المزود المحاولة).

مثال على التحقق من التنفيذ الموحد في Python:

processed_events = set()  # In production, use a database or cache

@app.route('/webhook', methods=['POST'])
def webhook():
    # ... signature verification ...
    event = request.json
    event_id = event['id']
    if event_id in processed_events:
        return '', 200  # Already processed
    # Process event
    processed_events.add(event_id)
    return '', 200

اختبار تنفيذ Webhook الخاص بك

قبل الانتقال إلى الإنتاج، اختبر نقطة النهاية الخاصة بك بدقة:

1. محاكاة الطلبات الموقعة: اكتب اختبارات وحدة تولد توقيعات صالحة وغير صالحة.
2. اختبار سيناريوهات إعادة المحاولة: حاكي حالات الفشل وتأكد من أن نقطة النهاية الخاصة بك تتعامل مع التكرارات.
3. استخدم أدوات المزود: يقدم العديد من المزودين واجهة سطر أوامر أو لوحة تحكم لإرسال أحداث اختبارية.
4. المراقبة والتسجيل: سجل الأحداث الواردة (بدون بيانات حساسة) وقم بإعداد تنبيهات لفشل التوقيع أو معدلات الخطأ العالية.

مقارنة: الاستقصاء مقابل Webhooks

الأسئلة الشائعة

كيف أتحقق من توقيع webhook؟

احسب HMAC لجسم الطلب الخام باستخدام المفتاح السري المشترك وقارنه برأس التوقيع باستخدام دالة مقارنة في وقت ثابت. تحقق دائمًا قبل معالجة الحمولة.

ماذا يجب أن تُرجع نقطة النهاية الخاصة بي لتأكيد استلام webhook؟

أعد رمز حالة 2xx (على سبيل المثال، 200 OK) بمجرد استلام الحدث ووضعه في قائمة الانتظار للمعالجة. تجنب المعالجة الطويلة في معالج الطلب لمنع المهلات.

كيف يمكنني التعامل مع تسليمات webhook المكررة؟

استخدم مفتاح التنفيذ الموحد من حمولة الحدث (أو معرف حدث فريد) لتتبع الأحداث المعالجة. قم بتخزين هذه المعرفات في قاعدة بيانات أو ذاكرة تخزين مؤقت وتخطَّ المعالجة إذا تم رؤية المعرف من قبل.

هل أنت مستعد لاختبار حمولات webhook الخاصة بك؟ استخدم JSON Formatter الخاص بنا لتنسيق والتحقق من جسم JSON لـ webhooks الواردة، مما يسهل تصحيح الأخطاء.