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

Backend2026-11-14TryQuickToolBox

لقد قمت ببناء API وتحتاج الآن إلى إخطار الخدمات الأخرى عند حدوث الأحداث. الاستقصاء (polling) غير فعال، لذا تقوم بتنفيذ webhooks. ولكن سرعان ما تدرك: كيف تتأكد من أن الحمولة (payload) أصلية؟ ماذا لو كان المستقبل متوقفًا؟ بدون تدابير حماية مناسبة، يمكن أن تصبح webhooks ثغرة أمنية وكابوسًا للموثوقية.

في هذه المقالة، سنستعرض أساسيات webhooks، مع التركيز على جانبين حاسمين: الحمولات الموقعة للأمان وآليات إعادة المحاولة للموثوقية. سنقدم أمثلة عملية على الكود وأفضل الممارسات لمساعدتك في بناء أنظمة webhook قوية.

ما هي Webhooks؟

Webhooks هي عمليات استدعاء HTTP (callbacks) يحددها المستخدم. تسمح لنظام بإرسال بيانات في الوقت الفعلي إلى نظام آخر عند حدوث حدث معين. على عكس واجهات API حيث تقوم بسحب البيانات، تقوم webhooks بدفع البيانات إليك. وهذا يجعلها مثالية للهندسات المعتمدة على الأحداث (event-driven).

تشمل حالات الاستخدام الشائعة إشعارات الدفع (مثل Stripe)، ومحفزات CI/CD (مثل GitHub)، ومنصات المراسلة (مثل Slack). يقوم المرسل بإجراء طلب HTTP POST إلى عنوان URL يقدمه المستقبل، مع حمولة تحتوي على تفاصيل الحدث.

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

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

يتضمن التوقيع عادةً إنشاء HMAC (رمز مصادقة الرسالة القائم على التجزئة) للحمولة باستخدام مفتاح سري. يتم إرسال التوقيع في رأس (header) (مثل X-Signature). يعيد المستقبل حساب HMAC ويقارنه بالتوقيع المستلم.

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

لنرى مثالاً بسيطًا في Python باستخدام Flask. يحسب المرسل التوقيع:

import hmac
import hashlib
import json
import requests

secret = b'your_shared_secret'
payload = {'event': 'payment.success', 'amount': 100}
body = json.dumps(payload).encode('utf-8')
signature = hmac.new(secret, body, hashlib.sha256).hexdigest()

headers = {'Content-Type': 'application/json', 'X-Signature': signature}
requests.post('https://receiver.com/webhook', data=body, headers=headers)

يتحقق المستقبل من التوقيع:

from flask import Flask, request, abort
import hmac
import hashlib

app = Flask(__name__)
secret = b'your_shared_secret'

@app.route('/webhook', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Signature')
    body = request.get_data()
    expected = hmac.new(secret, body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(signature, expected):
        abort(401)
    # Process payload
    return '', 200

أفضل الممارسات:

تنفيذ إعادة المحاولة الموثوقة

يمكن أن يفشل تسليم webhook بسبب مشكلات الشبكة أو توقف المستقبل أو أخطاء المعالجة. يجب على النظام القوي إعادة محاولة التسليمات الفاشلة باستخدام تأخير أسي (exponential backoff).

استراتيجية إعادة المحاولة

النهج الشائع: إعادة المحاولة حتى N مرة مع تأخيرات متزايدة (مثل 1 ثانية، 5 ثوانٍ، 30 ثانية، 5 دقائق، 30 دقيقة). بعد استنفاد المحاولات، قم بتمييز التسليم على أنه فاشل وتنبيه.

إليك آلية إعادة محاولة بسيطة في Python باستخدام مكتبة requests و tenacity:

from tenacity import retry, stop_after_attempt, wait_exponential
import requests

@retry(stop=stop_after_attempt(5), wait=wait_exponential(multiplier=1, min=1, max=60))
def send_webhook(url, payload, signature):
    headers = {'X-Signature': signature}
    response = requests.post(url, json=payload, headers=headers, timeout=10)
    response.raise_for_status()
    return response

أفضل الممارسات لإعادة المحاولة:

مقارنة: الحمولات الموقعة مقابل المصادقة الأساسية

النهجالأمانالتعقيدحماية إعادة التشغيل
المصادقة الأساسيةمنخفض (يتم إرسال بيانات الاعتماد في كل مرة)منخفضلا
الحمولة الموقعة (HMAC)عاليمتوسطنعم (مع طابع زمني)

خطوة بخطوة: بناء مرسل webhook مع إعادة المحاولة

  1. حدد حمولة الحدث وقم بتضمين معرف حدث فريد وطابع زمني.
  2. احسب التوقيع باستخدام HMAC-SHA256 على النص الأصلي.
  3. أرسل الطلب مع التوقيع في رأس.
  4. تعامل مع الفشل عن طريق إعادة المحاولة باستخدام تأخير أسي.
  5. سجل التسليمات ووفر الرؤية.

اختبار Webhooks

استخدم أدوات مثل ngrok لكشف خادمك المحلي واختبار تسليم webhook. تحقق دائمًا من التوقيعات في اختباراتك لاكتشاف المشكلات مبكرًا.

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

ما هي الحمولة الموقعة في webhooks؟

الحمولة الموقعة هي طلب webhook حيث يقوم المرسل بتضمين توقيع تشفيري (عادة HMAC) تم إنشاؤه باستخدام سر مشترك. يتحقق المستقبل من التوقيع لتأكيد أن الطلب أصلي ولم يتم العبث به.

كم مرة يجب أن أعيد محاولة webhook فاشل؟

لا يوجد عدد ثابت، لكن الممارسة الشائعة هي 3 إلى 5 محاولات مع تأخير أسي. ضع في اعتبارك وقت التوقف النموذجي للمستقبل وأهمية الحدث. اسمح دائمًا بإعادة المحاولة اليدوية.

هل يمكنني استخدام JWT لتوقيعات webhook؟

نعم، يمكن استخدام JWT، لكنه أكثر تعقيدًا. توقيعات HMAC أبسط وكافية لمعظم الحالات. إذا كنت بحاجة إلى تضمين مطالبات (claims)، فقد يكون JWT مناسبًا.

هل أنت مستعد لاختبار حمولات webhook الخاصة بك؟ استخدم JSON Formatter الخاص بنا للتحقق من حمولات JSON الخاصة بك وتنسيقها بشكل جميل قبل الإرسال.