TryQuickToolBox

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

Backend2026-10-24TryQuickToolBox

لقد قمت ببناء API وتحتاج الآن إلى إخطار الخدمات الأخرى عند حدوث الأحداث. قمت بإعداد نقطة نهاية webhook، لكنك تدرك بسرعة أن تسليم طلبات HTTP بشكل موثوق أصعب مما يبدو. يمكن أن تسبب أعطال الشبكة والمهاجمين الخبثاء والأحداث المكررة الفوضى. يشرح هذا الدليل كيفية تنفيذ webhooks مع حمولات موقعة وإعادة المحاولة حتى تتمكن من بناء تكامل قوي.

ما هي Webhooks؟

Webhooks هي عمليات استدعاء HTTP معرفة من قبل المستخدم. عند حدوث حدث في تطبيقك، ترسل طلب HTTP POST إلى عنوان URL يقدمه المشترك. هذا يسمح بالتواصل في الوقت الفعلي بين الخدمات دون استقصاء.

على سبيل المثال، قد يرسل معالج الدفع webhook إلى تطبيقك عند نجاح عملية دفع. يمكن لتطبيقك بعد ذلك تحديث حالة الطلب على الفور.

لماذا توقيع حمولات Webhook؟

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

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

كيفية إنشاء التوقيعات والتحقق منها

تستخدم معظم التطبيقات HMAC-SHA256. إليك مثال بسيط في Python:

import hmac
import hashlib
import json

def generate_signature(payload, secret):
    body = json.dumps(payload, separators=(',', ':')).encode('utf-8')
    signature = hmac.new(secret.encode('utf-8'), body, hashlib.sha256).hexdigest()
    return signature

def verify_signature(payload, signature, secret):
    expected = generate_signature(payload, secret)
    return hmac.compare_digest(expected, signature)

عند إرسال webhook، قم بتضمين التوقيع في رأس مثل X-Signature. يستخرج المستقبل النص الأصلي، ويعيد حساب HMAC، ويقارن. استخدم دائمًا دالة مقارنة ثابتة الوقت لمنع هجمات التوقيت.

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

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

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

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

أعد المحاولة فقط في ظروف محددة: أخطاء الشبكة، استجابات 5xx، أو 429 (طلبات كثيرة جدًا). لا تعد المحاولة في أخطاء 4xx (باستثناء 429) لأنها تشير إلى خطأ من العميل لن يتم إصلاحه بإعادة المحاولة.

مثال على منطق إعادة المحاولة

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

import requests
import time
from requests.exceptions import RequestException

def send_webhook(url, payload, secret, max_retries=5):
    headers = {'Content-Type': 'application/json'}
    signature = generate_signature(payload, secret)
    headers['X-Signature'] = signature
    
    for attempt in range(max_retries):
        try:
            response = requests.post(url, json=payload, headers=headers, timeout=10)
            if response.status_code < 500 and response.status_code != 429:
                return response.status_code
        except RequestException:
            pass
        
        # Exponential backoff with jitter
        delay = (2 ** attempt) + (random.random() * 0.1)
        time.sleep(delay)
    
    return None  # Failed after retries

في الإنتاج، ستخزن المحاولات الفاشلة في قائمة انتظار وتعالجها بشكل غير متزامن. يمكن أن تساعد أدوات مثل Celery أو قوائم انتظار السحابة (AWS SQS، Google Cloud Tasks).

أفضل الممارسات لأمان Webhook

التعامل مع التكرارات والتناسب

يمكن أن تسبب إعادة المحاولة عمليات تسليم مكررة. قم بتضمين معرف حدث فريد في الحمولة واطلب من المستقبل تتبع المعرفات المعالجة. إذا تم رؤية معرف حدث من قبل، فتجاهله.

بدلاً من ذلك، صمم معالجات الأحداث الخاصة بك لتكون متناسبة. على سبيل المثال، تحديث سجل بنفس البيانات عدة مرات يجب أن يكون له نفس تأثير القيام بذلك مرة واحدة.

اختبار Webhooks

استخدم أدوات مثل ngrok لكشف خادمك المحلي واختبار تسليم webhook. حاكي حالات الفشل عن طريق إرجاع رموز الخطأ وتحقق من حدوث إعادة المحاولة كما هو متوقع.

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

ما هي حمولة webhook الموقعة؟

تتضمن الحمولة الموقعة توقيعًا تشفيريًا (عادة HMAC) يسمح للمستقبل بالتحقق من أن الطلب جاء من مصدر موثوق ولم يتم تغييره.

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

يعتمد ذلك على احتياجات الموثوقية لديك. الممارسة الشائعة هي 5-10 محاولات إعادة مع تراجع أسي على مدار 24 ساعة. اسمح دائمًا للمشتركين بتشغيل إعادة المحاولة يدويًا.

هل يمكنني استخدام webhooks بدون توقيع؟

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

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