هندسة البرمجيات والـ Backend الأدلة التقنية

Webhooks: كيف ترسل الأحداث بين الأنظمة وتستقبلها بأمان

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

Webhooks: كيف ترسل الأحداث بين الأنظمة وتستقبلها بأمان

تربط متجرك ببوابة دفع، والعميل يضغط «ادفع» فينتقل إلى صفحة البوابة، ثم يعود إلى متجرك بعد دقيقة. والسؤال الذي يواجهه كل مطور في هذه اللحظة: كيف يعرف المتجر أن الدفع نجح فعلاً؟ قد يغلق العميل المتصفح قبل أن يعود، وقد يتأخر البنك في التأكيد عشر دقائق، وقد يرفض البنك العملية بعد ساعة لأن البطاقة مسروقة. فإذا اعتمدت على عودة العميل إلى صفحة «شكراً لك» فسوف تشحن طلبات لم تدفع، وتترك طلبات مدفوعة معلقة. والحل الذي تستخدمه كل بوابات الدفع ومنصات الشحن ومستودعات الكود اليوم أن يرسل لك النظام الآخر طلب HTTP إلى عنوان تحدده أنت كلما حدث شيء يهمك، وهذا الطلب هو الـ Webhook.

والفكرة تبدو بسيطة: عنوان URL يستقبل طلب POST فيه JSON. ولكن هذا العنوان مفتوح على الإنترنت، وأي شخص يعرفه يستطيع أن يرسل إليه «الدفع نجح»، والطرف المرسل سوف يعيد الإرسال إذا تأخرت في الرد فتصلك الرسالة مرتين، والرسائل قد تصل بغير ترتيبها، وسيرفرك قد يكون متوقفاً للتحديث في اللحظة التي يصل فيها أهم حدث في اليوم. وفي هذا المقال سوف نبني مرسلاً ومستقبلاً حقيقيين ونرى كل واحدة من هذه المشكلات تحدث أمامنا، ثم نصلحها.

وسوف نناقش في هذا المقال ما يلي:

  • ما هو الـ Webhook، ومتى تختاره بدل الاستطلاع الدوري Polling.
  • شكل الرسالة من الداخل، والمواصفة المفتوحة Standard Webhooks التي توحد الرؤوس Headers والتوقيع.
  • ما الذي لا يضمنه أي Webhook: الوصول، والتكرار، والترتيب، والمصدر.
  • التوقيع بالـ HMAC كما تفعله GitHub وStripe والمواصفة، ولماذا يجب أن تتحقق على النص الخام Raw Body.
  • منع إعادة الإرسال Replay Attack بالطابع الزمني Timestamp، ومنع التكرار بمعرف الرسالة Idempotency Key.
  • الرد السريع، وجدول الوارد Inbox وعامل Worker يعالج الرسائل بعد ذلك.
  • جهة الإرسال: إعادة المحاولة Retry مع التأخير الأسي Exponential Backoff، والمهلة Timeout، وحماية سيرفرك من عناوين يكتبها عملاؤك.
  • تجربة عملية فيها مرسل ومستقبل وقاعدة بيانات، نعيد فيها كل عطل: توقيع خاطئ، ومهلة تنتهي فتتكرر الرسالة، ورسالة مسروقة يعاد إرسالها، ورسائل بغير ترتيبها، ومستقبل متوقف.

ما هو الـ Webhook؟

الـ Webhook طلب HTTP يرسله نظام إلى نظام آخر عندما يقع حدث، إلى عنوان سجله النظام الثاني مسبقاً. فبدل أن يسأل متجرك بوابة الدفع كل دقيقة «هل دفع العميل؟»، تخبره البوابة بنفسها عندما يحدث ذلك. ولذلك يسميه البعض «الواجهة العكسية Reverse API»، لأن الطرف الذي يقدم الخدمة هو الذي يبدأ الطلب هذه المرة، ويسميه آخرون رد النداء عبر HTTP، أي HTTP Callback. وإذا لم تكن واضحاً لديك أساسيات الطلب والرد ورموز الحالة Status Codes فقد شرحناها في ما هي واجهة API.

وستجد الـ Webhooks في كل مكان تقريباً: GitHub يرسل حدث push إلى خادم CI عند كل Commit، وبوابة الدفع ترسل payment.succeeded، ومزود البريد التفاعلي يرسل «الرسالة ارتدت Bounce» أو «المستلم أبلغ أنها مزعجة» كما ذكرنا في Transactional Email، وأدوات الأتمتة مثل n8n تبدأ سير العمل كله من Webhook. والعلاقة دائماً بين طرفين: المرسل Provider الذي يقع عنده الحدث، والمستقبل Consumer الذي يريد أن يعرف به، وسوف نتحدث في هذا المقال عن الجهتين، لأنك غالباً سوف تكون مستقبلاً لـ Webhooks غيرك اليوم، ومرسلاً لعملائك غداً.

الاستطلاع الدوري Polling أم Webhook؟

قبل الـ Webhook كانت الطريقة الوحيدة هي الاستطلاع الدوري Polling: ترسل كل دقيقة طلباً تسأل فيه عن الجديد. وهذه الطريقة ليست خاطئة دائماً، ولكن لها ثمناً واضحاً، فإذا كان عندك 10,000 طلب معلق وتسأل عن كل طلب كل دقيقة فهذه 14 مليون طلب في اليوم، أغلبها يعود بإجابة «لا جديد»، والبوابة سوف تحدد لك معدل الطلبات Rate Limiting قبل أن تصل إلى هذا الرقم، كما شرحنا في تحديد معدل الطلبات. ومع ذلك يبقى العميل ينتظر حتى دقيقة كاملة ليعرف أن طلبه قبل. والجدول التالي يقارن بين الطريقتين:

المعيارالاستطلاع الدوري Pollingالـ Webhook
متى تعرف بالحدث؟بعد الدورة التالية، أي حتى دقيقة أو أكثرخلال ثوان من وقوعه
عدد الطلباتكثير، وأغلبها بلا فائدةطلب واحد لكل حدث، مع إعادة المحاولة عند الفشل
من يتحمل العطل؟أنت: إذا توقفت تعود وتسألالمرسل: يجب أن يعيد المحاولة، وأنت يجب أن تكون متاحاً
يحتاج عنواناً عاماً؟لا، أنت من يبدأ الاتصالنعم، عنوان HTTPS يصل إليه المرسل
الأمانأنت تتحقق من هوية السيرفر عبر TLSيجب أن تتحقق أنت من أن الرسالة من المرسل فعلاً
الترتيب والتكرارتقرأ الحالة الحالية، فلا مشكلةقد تصل الرسالة مرتين أو بغير ترتيبها

لاحظ السطر الأخير، لأنه يفسر نصف هذا المقال: الاستطلاع يقرأ الحالة الحالية دائماً، أما الـ Webhook فيخبرك بحدث وقع في لحظة ما، وقد تصلك أحداث قديمة بعد أحداث جديدة. لذلك الممارسة التي تنصح بها أغلب المنصات هي الجمع بين الاثنين: الـ Webhook ليعرف التطبيق فوراً، ومهمة دورية بطيئة تقارن الحالة مع واجهة المرسل كل ساعة مثلاً، لتلتقط ما ضاع لأي سبب، وتسمى هذه المقارنة المصالحة Reconciliation. وفي الاتجاه المقابل، إذا كان المستقبل متصفحاً وليس سيرفراً فالـ Webhook لا يناسبه، لأن المتصفح لا يملك عنواناً عاماً، وهنا تأتي الطرق التي شرحناها في التواصل اللحظي Polling وSSE وWebSocket.

كيف تبدو رسالة الـ Webhook من الداخل؟

كل منصة صممت رسائلها بطريقتها لسنوات، فـ GitHub يضع نوع الحدث في رأس X-GitHub-Event ومعرف التسليم في X-GitHub-Delivery والتوقيع في X-Hub-Signature-256، وStripe يضع كل شيء في رأس واحد اسمه Stripe-Signature. ولذلك اجتمعت عدة شركات على مواصفة Standard Webhooks المفتوحة، التي تحدد ثلاثة رؤوس وشكلاً للرسالة وطريقة للتوقيع، وهي ما سوف نستخدمه في التجربة. والرسالة حسب المواصفة تبدو هكذا:

POST /webhooks HTTP/1.1
Host: shop.example.com
Content-Type: application/json
webhook-id: msg_pay_1001
webhook-timestamp: 1795000000
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=

{"type":"payment.succeeded","timestamp":"2026-11-18T10:45:42+00:00","data":{"order_id":1001,"amount":"250.00"}}

في الرسالة أعلاه لاحظ التالي:

  • webhook-id: معرف فريد للرسالة، يبقى كما هو في كل محاولات إعادة الإرسال، وهو ما تستخدمه لمنع التكرار.
  • webhook-timestamp: وقت التوقيع بالثواني منذ 1970، أي Unix Time، وتستخدمه لرفض الرسائل القديمة.
  • webhook-signature: التوقيع مسبوقاً برقم النسخة v1، وقد يحتوي أكثر من توقيع مفصولة بمسافة أثناء تغيير السر.
  • الجسم: فيه نوع الحدث type بنقاط تفصل أجزاءه، ووقت وقوع الحدث، والبيانات data. وتنصح المواصفة أن يبقى أقل من 20 كيلوبايت، وأن ترسل رابطاً للملفات الكبيرة بدل وضعها في الرسالة.

وهناك قرار تصميم مهم في محتوى الرسالة: هل ترسل الكائن كاملاً كما كان لحظة الحدث، أم ترسل معرفه فقط ونوع الحدث، فيعود المستقبل ويطلب الحالة الحالية من الواجهة API؟ وStripe مثلاً يقدم النوعين، ويسمي الأول Snapshot والثاني Thin، وينصح بالثاني للتكاملات الجديدة. والرسالة النحيفة Thin أصغر، ولا تحمل بيانات حساسة إذا سرقت، ولا تسبب مشكلة الترتيب لأن المستقبل يقرأ دائماً أحدث حالة، وثمنها طلب إضافي إلى المرسل مع كل حدث.

ما الذي لا يضمنه لك أي Webhook؟

إذا قرأت توثيق أي منصة كبيرة سوف تجد الجمل نفسها بصيغ مختلفة، فتوثيق Stripe يقول صراحة إن نقطة الاستقبال قد تستقبل الحدث نفسه أكثر من مرة، وإن Stripe لا تضمن وصول الأحداث بترتيب حدوثها، وتوثيق GitHub يطلب منك أن تعيد طلب التسليمات التي فاتتك إذا كان سيرفرك متوقفاً. ونجمع هذا في ست حقائق يجب أن يبنى عليها كل مستقبل:

  1. قد لا تصل: سيرفرك متوقف، أو الشبكة انقطعت، أو المرسل نفسه تعطل، وبعض المرسلين يعيدون المحاولة لأيام وبعضهم لا يعيد إطلاقاً.
  2. قد تصل مرتين أو أكثر: إذا تأخر ردك عن مهلة المرسل اعتبر المحاولة فاشلة وأعاد الإرسال، حتى لو كنت قد نفذت العمل فعلاً.
  3. قد تصل بغير ترتيبها: حدث «تم الشحن» قد يصل قبل «تم التغليف»، لأن الأول نجح من المحاولة الأولى والثاني من الثالثة.
  4. قد تتأخر: رسالة تنتظر في جدول إعادة المحاولة ساعتين ثم تصل، والحالة تغيرت بعدها.
  5. قد لا تكون من المرسل: العنوان عام، وأي شخص يستطيع أن يرسل إليه JSON يشبه رسالة الدفع.
  6. قد تكون رسالة حقيقية قديمة: شخص حصل على نسخة من رسالة صحيحة، من سجل Logs مكشوف مثلاً، فيرسلها مرة ثانية بعد يوم.

والقسم التالي يأخذ كل حقيقة ويضع أمامها الحل، والصورة التالية تجمعها في مكان واحد:

ست بطاقات: قد لا تصل الرسالة، وقد تصل مرتين، وقد تصل بغير ترتيبها، وقد تتأخر ساعات، وقد لا تكون من المرسل، وقد تكون نسخة قديمة مسروقة، وتحت كل بطاقة الحل: إعادة المحاولة والمصالحة، وحفظ المعرف، ورقم التسلسل، وقراءة وقت الحدث، وتوقيع HMAC، والطابع الزمني
كل مستقبل Webhooks يبنى على هذه الحقائق الست، ولكل منها حل معروف

كيف تتأكد أن الرسالة من المرسل؟ التوقيع بالـ HMAC

الطرق السهلة أولاً، ولماذا لا تكفي. الطريقة الأولى أن تضع سراً في العنوان نفسه، مثل /webhooks?token=abc، وهذه أسوأ الطرق، لأن العنوان يظهر في سجلات الـ Reverse Proxy وأدوات المراقبة وسجل المتصفح لكل من يفتحه، ومن يرى السر مرة يستطيع أن يرسل ما يشاء إلى الأبد. والطريقة الثانية أن تقبل الطلبات من عناوين IP المرسل فقط، وهي مفيدة كطبقة إضافية، وتنشر GitHub وStripe عناوينها لهذا الغرض، ولكنها وحدها لا تكفي لأن العناوين تتغير، ولأن السيرفر قد يكون خلف موزع لا يمرر عنوان المرسل الحقيقي. والطريقة الثالثة كلمة مرور في رأس Authorization، وهذه تثبت من أرسل ولكنها لا تثبت أن المحتوى لم يتغير في الطريق، وتبقى كلمة المرور نفسها في كل طلب.

والحل الذي تستخدمه كل المنصات هو رمز مصادقة الرسالة HMAC، واختصاراً لـ Hash-based Message Authentication Code. والفكرة أن المرسل والمستقبل يشتركان في سر Secret لا يرسل أبداً مع الرسالة، والمرسل يحسب HMAC للرسالة بهذا السر ويضع الناتج في رأس الطلب، والمستقبل يحسب HMAC للرسالة التي وصلته بالسر نفسه ويقارن. فإذا تغير حرف واحد في الرسالة، أو حسبها شخص لا يملك السر، تغير الناتج كلياً. وقد شرحنا لماذا لا يكفي الهاش وحده وكيف يعمل HMAC في التشفير للمطورين. والفرق بين المنصات الثلاث المشهورة هو ما يدخل في الحساب وكيف يكتب الناتج:

المنصةالرأسما يوقعشكل الناتج
GitHubX-Hub-Signature-256الجسم فقطsha256= ثم الناتج بالنظام الست عشري Hex
StripeStripe-Signatureالطابع الزمني ثم نقطة ثم الجسمt=…,v1=… بالنظام الست عشري
Standard Webhookswebhook-signatureالمعرف ثم نقطة ثم الطابع الزمني ثم نقطة ثم الجسمv1, ثم الناتج بترميز Base64
ما يدخل في حساب HMAC: عند GitHub الجسم فقط بالنظام الست عشري، وعند Stripe الطابع الزمني ونقطة والجسم، وفي مواصفة Standard Webhooks المعرف ونقطة والطابع الزمني ونقطة والجسم بترميز Base64
كلما دخل في التوقيع أكثر صعب العبث بالرسالة أو إعادة إرسالها

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

# signing.py: sign and verify webhooks the Standard Webhooks way (the same scheme Svix and others use).
#   signed content = "{webhook-id}.{webhook-timestamp}.{raw body}"
#   signature      = "v1," + base64(HMAC-SHA256(secret, signed content))
import base64, hashlib, hmac, time

def secret_bytes(secret: str) -> bytes:
    return base64.b64decode(secret.removeprefix("whsec_"))

def sign(secret: str, msg_id: str, ts: int, body: bytes) -> str:
    mac = hmac.new(secret_bytes(secret), f"{msg_id}.{ts}.".encode() + body, hashlib.sha256).digest()
    return "v1," + base64.b64encode(mac).decode()

class Invalid(Exception):
    pass

def verify(secret: str, headers: dict, body: bytes, tolerance: int = 300) -> None:
    msg_id, ts, sigs = headers.get("webhook-id"), headers.get("webhook-timestamp"), headers.get("webhook-signature")
    if not (msg_id and ts and sigs):
        raise Invalid("missing webhook headers")
    now = int(time.time())
    if abs(now - int(ts)) > tolerance:                       # an old (replayed) or future message
        raise Invalid(f"timestamp too old or too new ({now - int(ts)}s)")
    expected = sign(secret, msg_id, int(ts), body)
    for s in sigs.split(" "):                                # several signatures while a secret is rotated
        if hmac.compare_digest(s, expected):                 # constant time, never ==
            return
    raise Invalid("no matching signature")

في الكود أعلاه لاحظ التالي:

  • السر يبدأ بـ whsec_: والباقي بايتات عشوائية بترميز Base64، والمواصفة تطلب أن يكون طولها بين 24 و64 بايتاً، لذلك نفك الترميز قبل الحساب ولا نستخدم النص كما هو.
  • الطابع الزمني يفحص قبل التوقيع: الرسالة القديمة ترفض مهما كان توقيعها صحيحاً، والمهلة هنا خمس دقائق، وهي المهلة الافتراضية في مكتبات Stripe.
  • hmac.compare_digest وليس ==: المقارنة العادية تتوقف عند أول حرف مختلف، فيستطيع المهاجم نظرياً أن يقيس الزمن ويخمن التوقيع حرفاً بعد حرف، والمقارنة ثابتة الزمن Constant-time تمنع ذلك، وتوثيق GitHub يقول صراحة «لا تستخدم المعامل ==».
  • أكثر من توقيع: عندما تغير السر يرسل المرسل توقيعين بالسرين القديم والجديد لفترة، فتقبل الرسالة إذا طابق أي منهما، وبذلك تغير السر دون أن تفقد رسالة واحدة.

لماذا يجب أن تتحقق على النص الخام Raw Body؟

هذه أشهر مشكلة يقع فيها المطورون مع الـ Webhooks، وتوثيق Stripe يضعها في صندوق تحذير خاص: لا تعدل جسم الطلب قبل التحقق. والسبب أن أغلب أطر العمل Frameworks تقرأ JSON وتحوله إلى كائن قبل أن يصل إلى الكود، والمطور يحسب التوقيع على json.dumps(event) وهو يظن أنه الجسم نفسه، وهو ليس كذلك: المسافات بعد الفواصل قد تختلف، وترتيب المفاتيح قد يختلف، والأحرف العربية قد تتحول إلى م، والأرقام العشرية قد تكتب بشكل آخر. والتوقيع محسوب على البايتات كما أرسلت، فأي اختلاف ولو بمسافة يفسده، وسوف نرى ذلك بالأرقام في التجربة. والقاعدة: اقرأ البايتات الخام أولاً، وتحقق منها، ثم حولها إلى JSON.

متى تحتاج توقيعاً بمفتاحين؟

في HMAC السر نفسه عند الطرفين، وهذا يعني أن المستقبل يستطيع نظرياً أن يصنع رسالة موقعة كأنها من المرسل. وهذا لا يهم في أغلب الحالات، لأن المستقبل لا مصلحة له في خداع نفسه، ولكنه يهم إذا كان المرسل يرسل الحدث نفسه إلى أطراف كثيرة بالسر نفسه، أو إذا أراد المستقبل أن يثبت لطرف ثالث أن الرسالة جاءت من المرسل. ولذلك تعرف المواصفة نسخة ثانية v2a توقع بمفتاح خاص Ed25519، ويتحقق المستقبل بالمفتاح العام فقط، وهو نفس مبدأ التوقيع الرقمي الذي شرحناه في GPG وOpenPGP.

منع إعادة الإرسال Replay Attack ومنع التكرار

التوقيع يثبت أن الرسالة من المرسل، ولكنه لا يثبت أنها جديدة. فإذا حصل شخص على رسالة «الدفع نجح» لطلب قيمته 50 ريالاً، من سجل مكشوف أو من أداة تصحيح نسيها أحد مفتوحة، فإنه يستطيع أن يرسلها مرة ثانية كما هي، والتوقيع سوف يكون صحيحاً لأنه لم يغير فيها شيئاً. وهذا ما يسمى هجوم إعادة الإرسال Replay Attack، والدفاع عنه بطبقتين:

  • الطابع الزمني داخل التوقيع: ترفض أي رسالة عمر توقيعها أكثر من خمس دقائق، والمهاجم لا يستطيع أن يحدث الوقت لأنه داخل التوقيع. وهذا يتطلب أن تكون ساعة سيرفرك صحيحة، فإذا انحرفت عشر دقائق سوف ترفض كل الرسائل الصحيحة، وقد شرحنا كيف تضبط الوقت وما الذي يتعطل إذا اختل في مزامنة الوقت NTP مع chrony.
  • معرف الرسالة: خلال الدقائق الخمس نفسها يستطيع المهاجم أن يعيد الرسالة، لذلك تحفظ معرف كل رسالة عالجتها، وترفض المعرف الذي رأيته من قبل، ويجب أن تحتفظ بالمعرفات مدة أطول من نافذة الطابع الزمني على الأقل.

والطبقة الثانية هي نفسها الحل لمشكلة مختلفة تماماً، وهي التكرار البريء: المرسل الذي أعاد الرسالة لأن ردك تأخر. ففي الحالتين تصلك رسالة بمعرف رأيته، والتصرف الصحيح أن ترد بنجاح 2xx دون أن تنفذ شيئاً، لأنك إذا رددت بخطأ فسوف يستمر المرسل في إعادة المحاولة. وقد شرحنا هذه الفكرة بالتفصيل، مع أين تحفظ المعرف ومتى تحذفه، في Idempotency: كيف تجعل العملية آمنة عند تكرارها. ويضيف توثيق Stripe ملاحظة دقيقة هنا: قد تنشئ المنصة أحياناً حدثين منفصلين بمعرفين مختلفين للتغيير نفسه، لذلك في العمليات الحساسة مثل تسجيل الدفع اجعل الحماية على مستوى العمل أيضاً، مثل قيد فريد على رقم العملية في جدول المدفوعات، وليس على معرف الرسالة فقط.

لماذا يجب أن ترد بسرعة؟ جدول الوارد Inbox

كل مرسل يضع مهلة Timeout للرد، فتوثيق GitHub يطلب أن يرد سيرفرك خلال 10 ثوان، والمواصفة تنصح المرسلين بمهلة بين 15 و30 ثانية، وتوثيق Stripe يقول إن عليك أن ترد بـ 2xx قبل أي منطق معقد قد يتسبب في انتهاء المهلة. والخطأ الشائع أن يكتب المطور كل العمل داخل الطلب: يتحقق، ثم يحدث الطلب في قاعدة البيانات، ثم يرسل بريد الإيصال، ثم يبلغ المستودع، ثم يرد. وفي يوم عادي يأخذ هذا ثانيتين فيمر، وفي يوم يبطئ فيه سيرفر البريد يأخذ ثمان ثوان، فتنتهي مهلة المرسل، فيعيد الإرسال، فينفذ العمل مرة ثانية وثالثة، وهذا بالضبط ما سوف نراه في التجربة: ثلاث رسائل إيصال لعملية دفع واحدة.

والشكل الصحيح يشبه نمط Outbox الذي شرحناه في Saga ونمط Outbox ولكن في الاتجاه المعاكس، ويسمى غالباً جدول الوارد Inbox: المستقبل يتحقق من التوقيع والطابع الزمني، ثم يحفظ الرسالة الخام في جدول مفتاحه معرف الرسالة، ثم يرد فوراً. وعامل Worker منفصل يقرأ الجدول ويعالج الرسائل بالسرعة التي يتحملها النظام، وإذا فشل في معالجة رسالة يعيد المحاولة هو، دون أن يزعج المرسل. وتوثيق Stripe يذكر سبباً إضافياً: في أول كل شهر تتجدد كل الاشتراكات فتصل آلاف الرسائل في دقائق، والطابور هو ما يمنع هذه الموجة من إسقاط السيرفر. وإذا كنت تستخدم وسيط رسائل فالفكرة نفسها تنطبق، وقد شرحناها في مفاهيم الطوابير Queue.

مسار الرسالة: المرسل يرسل POST إلى نقطة الاستقبال، التي تقرأ البايتات الخام وتفحص الطابع الزمني والتوقيع ثم تدخل الرسالة في جدول الوارد وترد 204، ثم يأخذ العامل الرسالة بقفل SKIP LOCKED ويرسل البريد ويحدث الطلب
تحقق واحفظ ورد خلال أجزاء من الثانية، واترك العمل الحقيقي للعامل

ماذا تفعل بالرسائل التي تصل بغير ترتيبها؟ Ordering

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

  1. اقرأ الحالة الحالية: اعتبر الرسالة مجرد تنبيه بأن شيئاً تغير، ثم اطلب الكائن من واجهة المرسل، فتحصل دائماً على أحدث حالة مهما كان ترتيب الرسائل. وهذا ما تفعله الرسائل النحيفة Thin.
  2. رقم نسخة Version أو تسلسل Sequence: إذا كان المرسل يضع رقماً يزيد مع كل تغيير للكائن، تحفظه مع الحالة، وتتجاهل أي رسالة رقمها أصغر من المحفوظ، وهذا ما نطبقه في التجربة بشرط seq < %s في جملة التحديث.
  3. آلة حالات State Machine: تعرف الانتقالات المسموحة، فالطلب الذي حالته «تم الشحن» لا يعود إلى «قيد التغليف»، وأي رسالة تطلب انتقالاً غير مسموح تسجل وتتجاهل.

إذا كنت أنت المرسل: Retries والمهلة وحماية سيرفرك

عندما يطلب منك عملاؤك أن يعرفوا بالأحداث في نظامك تصبح أنت المرسل، والمسؤولية هنا أكبر مما تبدو، لأنك ترسل طلبات إلى سيرفرات لا تملكها، بعضها بطيء وبعضها متوقف وبعضها يرد بأخطاء غريبة. وهذه أهم القرارات:

  • إعادة المحاولة مع تأخير أسي وعشوائية Exponential Backoff with Jitter: تنتظر بعد الفشل الأول قليلاً ثم تضاعف الانتظار، وتضيف عشوائية صغيرة حتى لا تعود كل الرسائل الفاشلة في اللحظة نفسها عندما يعود سيرفر العميل. والمواصفة تقترح جدولاً يمتد قرابة ثلاثة أيام: بعد 5 ثوان، ثم 5 دقائق، ثم 30 دقيقة، ثم ساعتين، ثم 5 و10 و14 و20 و24 ساعة. وStripe يعيد المحاولة حتى ثلاثة أيام في البيئة الحقيقية.
  • المعرف ثابت والتوقيع جديد: نفس webhook-id في كل محاولة حتى يستطيع المستقبل أن يكتشف التكرار، وطابع زمني وتوقيع جديدان في كل محاولة حتى لا ترفض المحاولة المتأخرة لأنها «قديمة».
  • مهلة معقولة: بين 15 و30 ثانية، ولا تنتظر أكثر، لأن كل اتصال معلق يحجز عاملاً عندك، وقانون Little يقول إن الاتصالات المعلقة تساوي المعدل مضروباً في الزمن.
  • تفسير رموز الرد: حسب المواصفة، 2xx نجاح، و3xx فشل ولا تتبع إعادة التوجيه بل اطلب من العميل تحديث العنوان، و410 Gone يعني أن العميل حذف النقطة فتوقف عن الإرسال إليها، و429 و502 و504 تعني أن السيرفر مضغوط فخفف المعدل، واحترم رأس Retry-After إذا جاء.
  • طابور لكل عميل: لا تجعل عميلاً بطيئاً يؤخر رسائل الجميع، فكل نقطة استقبال لها حصتها من العمال، وإذا فشلت أياماً متواصلة عطلها وأرسل لصاحبها بريداً.
  • سجل التسليمات وزر إعادة الإرسال: كل منصة جيدة تعرض للعميل كل محاولة بوقتها ورمز الرد، وتسمح له بإعادة إرسال رسالة يدوياً بعد أن يصلح سيرفره.
  • حماية سيرفرك من عناوين العملاء SSRF: العميل يكتب أي عنوان يريد، فإذا كتب http://169.254.169.254/ أو http://localhost:6379/ فإن سيرفرك هو الذي سوف يرسل الطلب إلى شبكتك الداخلية. لذلك احسم العنوان إلى IP، وارفض العناوين الخاصة والمحلية، وأرسل من شبكة معزولة. وهذا من مخاطر OWASP التي شرحناها في أمن الـ API مع OWASP.

وبناء كل هذا من الصفر عمل كبير، لذلك توجد أدوات مفتوحة المصدر متخصصة في إرسال الـ Webhooks، مثل Svix برخصة MIT وهي من الجهات التي تقف خلف المواصفة، وConvoy، وكل منهما يدير الطوابير وإعادة المحاولة والتوقيع وسجل التسليمات، وتستضيفهما على سيرفرك.

خط زمني من التجربة: المتجر متوقف أول 12 ثانية، والمحاولات عند 4.1 و9.2 و10.9 و14.3 ثانية فشلت، والخامسة عند 21.8 ثانية نجحت برد 204، وتحته جدول المواصفة: 5 ثوان ثم 5 دقائق ثم 30 دقيقة ثم ساعتان ثم 5 و10 و14 و20 و24 ساعة
التأخير الأسي مع العشوائية أنقذ الرسالة في التجربة، والجدول الحقيقي يمتد قرابة ثلاثة أيام

تجربة عملية Lab: مرسل ومستقبل وكل الأعطال

في هذه التجربة نبني نظاماً صغيراً من أربع Containers: قاعدة بيانات PostgreSQL للمتجر، والمتجر نفسه وهو مستقبل الـ Webhooks مكتوب بـ FastAPI، وعامل Worker يعالج الرسائل المحفوظة، وجهة الإرسال، وهي Container نشغل منه سكربت المرسل كأنه بوابة الدفع. والمتجر فيه ثلاث نقاط استقبال لنفس الحدث: نسخة خاطئة تتحقق من التوقيع بعد تحويل JSON، ونسخة تتحقق صحيحاً ولكنها تنفذ العمل داخل الطلب، ونسخة صحيحة تحفظ في جدول الوارد وترد فوراً. وكل الملفات في مجلد lab مع المقال.

ملفات التجربة

جداول المتجر: جدول الوارد inbox بمفتاح هو معرف الرسالة، وجدول الطلبات مع رقم التسلسل seq، وجدول الرسائل البريدية المرسلة حتى نعد الإيصالات:

CREATE TABLE inbox (
  webhook_id   text PRIMARY KEY,               -- the provider's message id: the duplicate check
  body         text NOT NULL,                  -- the raw body as received
  received_at  timestamptz NOT NULL DEFAULT now(),
  processed_at timestamptz
);
CREATE TABLE orders (id int PRIMARY KEY, status text NOT NULL, seq int NOT NULL DEFAULT 0);
CREATE TABLE emails (id serial PRIMARY KEY, order_id int NOT NULL, msg_id text NOT NULL, sent_at timestamptz DEFAULT now());
INSERT INTO orders VALUES (1001, 'pending', 0), (1002, 'pending', 0), (1003, 'pending', 0);

والمستقبل receiver.py بنقاطه الثلاث، والدالة apply_event التي تنفذ العمل الحقيقي: تسجل بريد الإيصال وتحدث الطلب عند الدفع، وتحدث حالة الطلب عند order.updated بشرط أن يكون رقم التسلسل أحدث:

# receiver.py: the shop's webhook endpoints (FastAPI). Three versions of the same endpoint.
import json, os, time
import psycopg
from fastapi import FastAPI, Request, Response
from signing import Invalid, sign, verify

SECRET = os.environ["WEBHOOK_SECRET"]
TOLERANCE = int(os.environ.get("TOLERANCE", "300"))
DB = os.environ["DATABASE_URL"]
app = FastAPI()

def log(*a):
    print(time.strftime("%H:%M:%S"), *a, flush=True)

# 1) The common mistake: parse the JSON first, then sign what we re-serialised
@app.post("/webhooks/naive")
async def naive(request: Request):
    event = await request.json()
    body_again = json.dumps(event).encode()
    try:
        verify(SECRET, request.headers, body_again, TOLERANCE)
    except Invalid as e:
        log("naive  REJECT", e, "| raw", len(await request.body()), "bytes, re-serialised", len(body_again), "bytes")
        return Response(status_code=401)
    return Response(status_code=204)

# 2) Correct signature, but all the work happens inside the request, with no duplicate check
@app.post("/webhooks/inline")
async def inline(request: Request):
    body = await request.body()
    try:
        verify(SECRET, request.headers, body, TOLERANCE)
    except Invalid as e:
        log("inline REJECT", e); return Response(status_code=401)
    event = json.loads(body)
    with psycopg.connect(DB, autocommit=True) as db:
        apply_event(db, request.headers["webhook-id"], event, slow=True)
    return Response(status_code=204)

# 3) The right shape: verify the raw body, store it once, answer at once; a worker does the work
@app.post("/webhooks")
async def inbox(request: Request):
    body = await request.body()
    try:
        verify(SECRET, request.headers, body, TOLERANCE)
    except Invalid as e:
        log("inbox  REJECT", request.headers.get("webhook-id"), e); return Response(status_code=401)
    msg_id = request.headers["webhook-id"]
    with psycopg.connect(DB, autocommit=True) as db:
        cur = db.execute("INSERT INTO inbox (webhook_id, body) VALUES (%s, %s) ON CONFLICT DO NOTHING", (msg_id, body.decode()))
    log("inbox  ACCEPT", msg_id, "new" if cur.rowcount else "duplicate, ignored")
    return Response(status_code=204)

def apply_event(db, msg_id, event, slow=False):
    """payment.succeeded marks the order paid and sends one receipt email."""
    d = event["data"]
    if event["type"] == "payment.succeeded":
        if slow:
            time.sleep(8)                                     # the receipt email over a slow SMTP server
        db.execute("INSERT INTO emails (order_id, msg_id) VALUES (%s, %s)", (d["order_id"], msg_id))
        db.execute("UPDATE orders SET status = 'paid' WHERE id = %s", (d["order_id"],))
    elif event["type"] == "order.updated":
        # keep the newest state only: an older event that arrives late changes nothing
        cur = db.execute("UPDATE orders SET status = %s, seq = %s WHERE id = %s AND seq < %s",
                         (d["status"], d["seq"], d["order_id"], d["seq"]))
        if cur.rowcount == 0:
            log("apply  STALE ", msg_id, "seq", d["seq"], "is older than the stored state, skipped")
            return
    log("apply  DONE  ", msg_id, event["type"], d)

والعامل worker.py يأخذ صفاً واحداً لم يعالج من جدول الوارد بقفل FOR UPDATE SKIP LOCKED، حتى نستطيع أن نشغل أكثر من عامل دون أن يأخذ اثنان الرسالة نفسها، وهي الطريقة التي شرحناها في PostgreSQL لكل شيء:

# worker.py: takes stored webhooks from the inbox table and applies them, one row at a time.
import json, os, time
import psycopg
from receiver import apply_event, log

DB = os.environ["DATABASE_URL"]
with psycopg.connect(DB) as db:
    while True:
        with db.transaction():
            row = db.execute("""SELECT webhook_id, body FROM inbox WHERE processed_at IS NULL
                                ORDER BY received_at LIMIT 1 FOR UPDATE SKIP LOCKED""").fetchone()
            if row:
                apply_event(db, row[0], json.loads(row[1]))
                db.execute("UPDATE inbox SET processed_at = now() WHERE webhook_id = %s", (row[0],))
        if not row:
            time.sleep(0.5)

والمرسل sender.py يبني الرسالة مرة واحدة بمعرف ثابت، ويعيد المحاولة حتى ست مرات بتأخير 1 ثم 2 ثم 4 ثم 8 ثوان مع عشوائية 20%، وهو جدول مختصر للتجربة بدل الأيام الثلاثة، ويتوقف فقط عند النجاح أو عند 410:

# sender.py: the payment provider's side. Delivers one event with retries, exponential backoff and jitter.
#   python sender.py URL TYPE JSON_DATA [--id msg_x] [--secret whsec_...] [--attempts 6] [--timeout 5] [--save f.json]
import argparse, json, os, random, time, uuid
from datetime import datetime, timezone
import httpx
from signing import sign

p = argparse.ArgumentParser()
p.add_argument("url"); p.add_argument("type"); p.add_argument("data")
p.add_argument("--id", default=None); p.add_argument("--secret", default=None)
p.add_argument("--attempts", type=int, default=6); p.add_argument("--timeout", type=float, default=5)
p.add_argument("--save", default=None)                    # keep a copy of the request (to test replays)
a = p.parse_args()

secret = a.secret or os.environ["WEBHOOK_SECRET"]
msg_id = a.id or "msg_" + uuid.uuid4().hex[:20]          # the same id on every retry
body = json.dumps({"type": a.type, "timestamp": datetime.now(timezone.utc).isoformat(timespec="seconds"),
                   "data": json.loads(a.data)}, ensure_ascii=False, separators=(",", ":")).encode()
start = time.monotonic()
for attempt in range(1, a.attempts + 1):
    ts = int(time.time())                                  # a new timestamp and signature for each attempt
    headers = {"content-type": "application/json", "webhook-id": msg_id,
               "webhook-timestamp": str(ts), "webhook-signature": sign(secret, msg_id, ts, body)}
    if a.save:
        json.dump({"headers": headers, "body": body.decode()}, open(a.save, "w"), ensure_ascii=False)
    t0 = time.monotonic()
    try:
        r = httpx.post(a.url, content=body, headers=headers, timeout=a.timeout)
        result = str(r.status_code)
    except httpx.HTTPError as e:
        result = type(e).__name__
    took = time.monotonic() - t0
    print(f"t={time.monotonic() - start:5.1f}s attempt {attempt} {msg_id} -> {result} in {took:.2f}s", flush=True)
    if result.startswith("2"):
        break
    if result == "410":                                    # 410 Gone: the receiver removed this endpoint
        print("   endpoint gone, disabling it"); break
    if attempt < a.attempts:
        delay = min(60, 2 ** (attempt - 1)) * random.uniform(0.8, 1.2)   # 1s, 2s, 4s, 8s ... with jitter
        print(f"   next attempt in {delay:.1f}s"); time.sleep(delay)

وملف Compose يجمع الأجزاء، والسر يأتي من ملف .env:

name: sw3-wh
services:
  db:
    image: postgres:18-alpine
    environment: { POSTGRES_PASSWORD: lab }
    volumes: [ "./schema.sql:/docker-entrypoint-initdb.d/schema.sql:ro" ]
    healthcheck: { test: ["CMD", "pg_isready", "-U", "postgres"], interval: 2s, retries: 30 }
  shop:                       # the receiver
    build: .
    image: sw3-wh-app:1
    command: uvicorn receiver:app --host 0.0.0.0 --port 8000
    environment: &env
      WEBHOOK_SECRET: ${WEBHOOK_SECRET}
      DATABASE_URL: postgresql://postgres:lab@db/postgres
      TOLERANCE: ${TOLERANCE:-300}
    depends_on: { db: { condition: service_healthy } }
  worker:                     # applies what the receiver stored
    image: sw3-wh-app:1
    command: python worker.py
    environment: *env
    depends_on: [ shop ]
  provider:                   # the sender: we run sender.py inside it
    image: sw3-wh-app:1
    command: sleep infinity
    environment: *env

ونولد سراً عشوائياً بطول 32 بايتاً بالشكل الذي تطلبه المواصفة، ثم نشغل كل شيء:

echo "WEBHOOK_SECRET=whsec_$(openssl rand -base64 32)" > .env
docker compose up -d --build --wait

هل توقيعنا متوافق؟ مقارنة مع المكتبة الرسمية ومثال GitHub

قبل أي شيء نتأكد أن الدالة التي كتبناها تحسب التوقيع كما تحسبه المكتبة الرسمية للمواصفة standardwebhooks، وأن طريقة GitHub تعطي الناتج المنشور في توثيقها للمثال الذي وضعته هناك:

# crosscheck.py: is our signing code compatible with the official library and with GitHub's documented example?
import hashlib, hmac, time
from standardwebhooks.webhooks import Webhook
from signing import sign, verify

secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"           # a test secret
body = '{"type":"payment.succeeded","data":{"order_id":1001,"customer":"متجر"}}'.encode()
ts = int(time.time())
ours = sign(secret, "msg_test_1", ts, body)
theirs = Webhook(secret).sign("msg_test_1", __import__("datetime").datetime.fromtimestamp(ts), body.decode())
print("ours  :", ours)
print("lib   :", theirs)
headers = {"webhook-id": "msg_test_1", "webhook-timestamp": str(ts), "webhook-signature": ours}
Webhook(secret).verify(body, headers)
print("standardwebhooks.verify accepted our signature")
verify(secret, headers, body)
print("our verify accepted it too")

# GitHub signs only the body, hex encoded, in X-Hub-Signature-256 (values from GitHub's docs)
gh = "sha256=" + hmac.new(b"It's a Secret to Everybody", b"Hello, World!", hashlib.sha256).hexdigest()
print("github:", gh)
print("matches the docs:", hmac.compare_digest(gh, "sha256=757107ea0eb2509fc211221cce984b8a37570b6d7586c22c46f4379c8b043e17"))
docker compose exec provider python crosscheck.py

والمخرج سوف يكون كما يلي:

ours  : v1,cLQnGjwFKXoMuVBqMVE298igr2+d6Jto+V5w6GOEtac=
lib   : v1,cLQnGjwFKXoMuVBqMVE298igr2+d6Jto+V5w6GOEtac=
standardwebhooks.verify accepted our signature
our verify accepted it too
github: sha256=757107ea0eb2509fc211221cce984b8a37570b6d7586c22c46f4379c8b043e17
matches the docs: True

التوقيعان متطابقان حرفاً بحرف، والمكتبة الرسمية قبلت توقيعنا، ومثال GitHub يعطي الناتج المنشور في صفحة التحقق من التسليمات للسر It's a Secret to Everybody والرسالة Hello, World!. وهذه خطوة لا تتركها إذا كتبت التحقق بنفسك: قارن مع مثال منشور قبل أن تثق بالكود، والأفضل في الإنتاج أن تستخدم المكتبة الرسمية للمرسل مباشرة.

الرسالة الأولى، والتحقق الخاطئ، والرسالة المزورة

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

S="docker compose exec -T provider python sender.py"
$S http://shop:8000/webhooks payment.succeeded '{"order_id":1001,"amount":"250.00","customer":"مؤسسة النخيل"}' --id msg_pay_1001
$S http://shop:8000/webhooks/naive payment.succeeded '{"order_id":1002,"amount":"99.00","customer":"مؤسسة النخيل"}' --id msg_pay_1002_naive --attempts 2
$S http://shop:8000/webhooks payment.succeeded '{"order_id":1002,"amount":"99.00"}' --secret whsec_d3Jvbmctc2VjcmV0LXdyb25nLXNlY3JldA== --id msg_forged_1 --attempts 2
docker compose logs --no-log-prefix shop worker | grep -v 'INFO:'

والمخرج سوف يكون كما يلي:

### 1 happy
t=  0.1s attempt 1 msg_pay_1001 -> ConnectError in 0.09s
   next attempt in 0.9s
t=  1.1s attempt 2 msg_pay_1001 -> 204 in 0.07s
### 2 naive
t=  0.1s attempt 1 msg_pay_1002_naive -> 401 in 0.12s
   next attempt in 1.2s
t=  1.3s attempt 2 msg_pay_1002_naive -> 401 in 0.03s
### 3 forged
t=  0.2s attempt 1 msg_forged_1 -> 401 in 0.20s
   next attempt in 1.2s
t=  1.4s attempt 2 msg_forged_1 -> 401 in 0.03s
### logs
10:45:43 apply  DONE   msg_pay_1001 payment.succeeded {'order_id': 1001, 'amount': '250.00', 'customer': 'مؤسسة النخيل'}
10:45:43 inbox  ACCEPT msg_pay_1001 new
10:45:44 naive  REJECT no matching signature | raw 147 bytes, re-serialised 201 bytes
10:45:46 naive  REJECT no matching signature | raw 147 bytes, re-serialised 201 bytes
10:45:48 inbox  REJECT msg_forged_1 no matching signature
10:45:49 inbox  REJECT msg_forged_1 no matching signature

في المخرج أعلاه لاحظ التالي:

  • المحاولة الأولى فشلت فعلاً: أرسلنا الرسالة بعد أن أعلن Docker أن الحاويات جاهزة، ولكن uvicorn لم يكن قد فتح المنفذ بعد، فجاء ConnectError، وانتظر المرسل 0.9 ثانية وأعاد فنجح. وهذا لم نخطط له، ولكنه أفضل مثال على أن إعادة المحاولة ليست رفاهية: سيرفر يعاد تشغيله لثانية واحدة كان سوف يضيع رسالة دفع.
  • المستقبل رد قبل أن يعالج: سطر inbox ACCEPT ثم سطر apply DONE من العامل، وترتيبهما في المخرج هو ترتيب الخدمتين في الأمر وليس ترتيب الوقت، فالوقت واحد تقريباً.
  • النقطة الخاطئة رفضت رسالة صحيحة: الجسم الذي وصل 147 بايتاً، والذي أعادت بناءه 201 بايت، فالتوقيع لا يمكن أن يطابق. والمرسل أعاد المحاولة لأن 401 ليست 410، وفي الإنتاج سوف يستمر ثلاثة أيام دون فائدة.
  • الرسالة المزورة رفضت: بالرسالة نفسها no matching signature، ولم يدخل شيء إلى الجدول، ولم يتغير الطلب 1002.

ولنرى لماذا تغير الحجم من 147 إلى 201 بايت، نحول رسالة صغيرة كما يفعل الكود الخاطئ:

{"type":"payment.succeeded","data":{"order_id":1002,"customer":"مؤسسة النخيل"}}
{"type": "payment.succeeded", "data": {"order_id": 1002, "customer": "\u0645\u0624\u0633\u0633\u0629 \u0627\u0644\u0646\u062e\u064a\u0644"}}
90 bytes -> 140 bytes

شيئان تغيرا: json.dumps أضاف مسافة بعد كل نقطتين وفاصلة، وحول كل حرف عربي إلى ستة أحرف م لأن الخيار الافتراضي ensure_ascii=True. والنص بعد التحويل يمثل الكائن نفسه تماماً، ولكنه بايتات مختلفة، والتوقيع يحسب على البايتات. لذلك إذا رأيت توقيعاً يفشل فقط عندما يكون في الرسالة حرف عربي أو رقم عشري، فابحث عن مكان يعيد فيه الكود بناء JSON قبل التحقق.

المهلة تنتهي فيتكرر العمل: ثلاثة إيصالات لدفعة واحدة

الآن نرسل دفعة للطلب 1002 إلى النقطة التي تعمل داخل الطلب، وفيها إرسال بريد الإيصال يأخذ ثماني ثوان كأن سيرفر البريد بطيء، والمرسل ينتظر خمس ثوان فقط:

$S http://shop:8000/webhooks/inline payment.succeeded '{"order_id":1002,"amount":"99.00"}' --id msg_pay_1002 --attempts 3
docker compose logs --no-log-prefix shop | grep -E 'inline|1002'
docker compose exec -T db psql -U postgres -c "SELECT order_id, msg_id, to_char(sent_at,'HH24:MI:SS') AS sent_at FROM emails ORDER BY id"

والمخرج سوف يكون كما يلي:

### 4 inline slow
t=  5.2s attempt 1 msg_pay_1002 -> ReadTimeout in 5.15s
   next attempt in 1.0s
t= 11.2s attempt 2 msg_pay_1002 -> ReadTimeout in 5.03s
   next attempt in 2.2s
t= 18.4s attempt 3 msg_pay_1002 -> ReadTimeout in 5.02s
10:46:26 apply  DONE   msg_pay_1002 payment.succeeded {'order_id': 1002, 'amount': '99.00'}
INFO:     172.27.0.3:36294 - "POST /webhooks/inline HTTP/1.1" 204 No Content
10:46:34 apply  DONE   msg_pay_1002 payment.succeeded {'order_id': 1002, 'amount': '99.00'}
INFO:     172.27.0.3:36296 - "POST /webhooks/inline HTTP/1.1" 204 No Content
10:46:42 apply  DONE   msg_pay_1002 payment.succeeded {'order_id': 1002, 'amount': '99.00'}
INFO:     172.27.0.3:37680 - "POST /webhooks/inline HTTP/1.1" 204 No Content
 order_id |    msg_id    | sent_at  
----------+--------------+----------
     1001 | msg_pay_1001 | 10:45:43
     1002 | msg_pay_1002 | 10:46:26
     1002 | msg_pay_1002 | 10:46:34
     1002 | msg_pay_1002 | 10:46:42
(4 rows)

هذه هي المشكلة كما تحدث في الإنتاج: المرسل يرى ثلاث محاولات فاشلة بـ ReadTimeout، والمتجر يرى ثلاثة طلبات ناجحة رد عليها بـ 204 بعد ثماني ثوان، والعميل يرى ثلاث رسائل إيصال لدفعة واحدة، كلها بالمعرف نفسه msg_pay_1002. ولاحظ أن الطرفين صادقان: المتجر نفذ العمل فعلاً، والمرسل لم يصله الرد فعلاً، والخطأ في التصميم وحده. ولو كان العمل «إضافة رصيد» بدل «إرسال بريد» لأضاف الرصيد ثلاث مرات.

جدول الوارد يحل المشكلتين: الرد السريع ومنع التكرار

نرسل دفعة الطلب 1003 إلى النقطة الصحيحة، ثم نرسلها مرة ثانية بالمعرف نفسه كأن المرسل أعادها، ونحفظ نسخة من الطلب في ملف cap.json كأن مهاجماً حصل عليه، ثم نعيد إرسال النسخة المحفوظة كما هي، ثم بطابع زمني جديد:

$S http://shop:8000/webhooks payment.succeeded '{"order_id":1003,"amount":"40.00"}' --id msg_pay_1003
$S http://shop:8000/webhooks payment.succeeded '{"order_id":1003,"amount":"40.00"}' --id msg_pay_1003 --save cap.json
docker compose exec -T provider python replay.py http://shop:8000/webhooks cap.json
docker compose exec -T provider python replay.py http://shop:8000/webhooks cap.json --new-timestamp

والمخرج سوف يكون كما يلي، مع سجل المتجر وعدد الإيصالات لكل طلب:

### 5 inbox + duplicate (second delivery of msg_pay_1003)
t=  0.2s attempt 1 msg_pay_1003 -> 204 in 0.23s
### 6 replay now
replay -> 204 | age of the captured request: 3 s
### 6b replay with new timestamp
replay -> 401 | age of the captured request: 7 s
10:47:36 inbox  ACCEPT msg_pay_1003 new
10:48:04 inbox  ACCEPT msg_pay_1003 duplicate, ignored
10:48:07 inbox  ACCEPT msg_pay_1003 duplicate, ignored
10:48:11 inbox  REJECT msg_pay_1003 no matching signature
10:47:37 apply  DONE   msg_pay_1003 payment.succeeded {'order_id': 1003, 'amount': '40.00'}
 order_id | emails 
----------+--------
     1001 |      1
     1002 |      3
     1003 |      1
(3 rows)

في المخرج أعلاه لاحظ التالي:

  • الرد في 0.23 ثانية: لأن المتجر لا يرسل بريداً داخل الطلب، وإنما يكتب صفاً واحداً ويرد، فلن تنتهي مهلة أي مرسل مهما كان سيرفر البريد بطيئاً.
  • التكرار قبل بنجاح ولم ينفذ: السطر duplicate, ignored ورد 204، وهذا هو التصرف الصحيح، لأن الرد بخطأ سوف يجعل المرسل يعيد المحاولة أياماً.
  • إعادة النسخة المسروقة خلال خمس دقائق: قبلها المتجر لأن التوقيع والطابع الزمني صحيحان، ولكنها لم تنفذ لأن المعرف موجود، وهذه هي الطبقة الثانية من الحماية.
  • تغيير الطابع الزمني أفسد التوقيع: رد 401 مع no matching signature، لأن الوقت جزء مما وقع عليه المرسل.
  • إيصال واحد للطلب 1003: مقابل ثلاثة للطلب 1002 في القسم السابق.

ماذا لو أعاد المهاجم الرسالة بعد انتهاء المهلة؟ What If

المعرفات المحفوظة تحمي خلال النافذة، ولكن ماذا لو حذفت المعرفات القديمة بعد أسبوع لتوفير المساحة، ثم أعاد المهاجم رسالة عمرها شهر؟ هنا يعمل فحص الطابع الزمني. ولكي لا ننتظر خمس دقائق نشغل المتجر بمهلة 30 ثانية، ثم نعيد النسخة المحفوظة:

TOLERANCE=30 docker compose up -d shop
docker compose exec -T provider python replay.py http://shop:8000/webhooks cap.json
### 7 replay after tolerance=30s
replay -> 401 | age of the captured request: 138 s
10:50:22 inbox  REJECT msg_pay_1003 timestamp too old or too new (138s)

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

الرسائل بغير ترتيبها

نرسل حالة «تم الشحن» برقم تسلسل 3، ثم تصل متأخرة حالة «تم التغليف» برقم 2:

$S http://shop:8000/webhooks order.updated '{"order_id":1002,"status":"shipped","seq":3}' --id msg_ord_1002_3
$S http://shop:8000/webhooks order.updated '{"order_id":1002,"status":"packed","seq":2}' --id msg_ord_1002_2
docker compose logs --no-log-prefix worker | grep msg_ord_1002
docker compose exec -T db psql -U postgres -c "SELECT * FROM orders ORDER BY id"
### 8 out of order
t=  0.2s attempt 1 msg_ord_1002_3 -> 204 in 0.24s
t=  0.3s attempt 1 msg_ord_1002_2 -> 204 in 0.26s
10:54:00 apply  DONE   msg_ord_1002_3 order.updated {'order_id': 1002, 'status': 'shipped', 'seq': 3}
10:54:03 apply  STALE  msg_ord_1002_2 seq 2 is older than the stored state, skipped
  id  | status  | seq 
------+---------+-----
 1001 | shipped |   3
 1002 | shipped |   3
 1003 | paid    |   0
(3 rows)

الرسالتان قبلتا بنجاح لأن كلتيهما صحيحة ومن المرسل، ولكن العامل تجاهل الثانية لأن الطلب يحمل رقماً أحدث، فبقيت الحالة shipped. ولو كان التحديث مجرد SET status = %s لعاد الطلب إلى «قيد التغليف» بعد شحنه، ولظهر في لوحة المستودع ليشحن مرة ثانية.

المستقبل متوقف: إعادة المحاولة تنقذ الرسالة

نوقف المتجر، ونرسل رسالة بثماني محاولات، ونعيد تشغيل المتجر بعد 12 ثانية من البداية:

docker compose stop shop
( sleep 12; docker compose start shop ) &
$S http://shop:8000/webhooks payment.succeeded '{"order_id":1001,"amount":"15.00","note":"refund fee"}' --id msg_pay_1001_fee --attempts 8
t=  4.1s attempt 1 msg_pay_1001_fee -> ConnectError in 4.12s
   next attempt in 1.1s
t=  9.2s attempt 2 msg_pay_1001_fee -> ConnectError in 3.92s
   next attempt in 1.7s
t= 10.9s attempt 3 msg_pay_1001_fee -> ConnectError in 0.03s
   next attempt in 3.4s
t= 14.3s attempt 4 msg_pay_1001_fee -> ConnectError in 0.02s
   next attempt in 7.4s
t= 21.8s attempt 5 msg_pay_1001_fee -> 204 in 0.04s

في المخرج أعلاه لاحظ التالي:

  • المحاولتان الأوليان أخذتا 4 ثوان لكل منهما: وليس أجزاء من الثانية، لأن الـ Container متوقف فلا يجد DNS الداخلي في Docker اسمه، فينتظر المرسل حتى يفشل البحث. وهذا يذكرك بأن الفشل نفسه قد يكون بطيئاً، وأن المهلة يجب أن تشمل الاتصال والبحث عن الاسم، وليس انتظار الرد فقط.
  • المحاولتان الثالثة والرابعة فشلتا في جزء من الثانية: عاد الاسم بعد بدء الـ Container ولكن uvicorn لم يفتح المنفذ بعد، فجاء الرفض فوراً.
  • التأخير تضاعف تقريباً: 1.1 ثم 1.7 ثم 3.4 ثم 7.4 ثانية، والعشوائية جعلته لا يطابق 1 و2 و4 و8 بالضبط، وهذا مقصود.
  • المحاولة الخامسة نجحت بعد 21.8 ثانية: ولم يلاحظ أحد أن المتجر كان متوقفاً، وهذا هو الهدف. ولو كان التوقف ساعتين فالجدول الحقيقي الذي يمتد ثلاثة أيام سوف يغطيه.

النتائج في جدول

الحالةالنقطة الخاطئة أو الداخليةجدول الوارد Inbox
رسالة صحيحة فيها نص عربيرفضت، 147 بايتاً صارت 201قبلت ونفذت مرة واحدة
رسالة بسر خاطئرفضترفضت
العمل يأخذ 8 ثوان والمهلة 53 محاولات فاشلة و3 إيصالاترد في 0.23 ثانية وإيصال واحد
تكرار بالمعرف نفسهينفذ كل مرة204 دون تنفيذ
نسخة مسروقة بطابع جديدرفضت، التوقيع لا يطابق
نسخة مسروقة بعد انتهاء النافذةرفضت، الطابع الزمني قديم
تسلسل 2 بعد تسلسل 3تجاهلها العامل، بقيت الحالة الأحدث
المستقبل متوقف 12 ثانيةنجحت المحاولة الخامسة بعد 21.8 ثانية
مقارنة: العمل داخل الطلب مع بريد يأخذ 8 ثوان ومهلة 5 ثوان أنتج 3 محاولات فاشلة و3 رسائل إيصال، وجدول الوارد رد في 0.23 ثانية وأنتج رسالة إيصال واحدة ورفض النسخة المسروقة
الدفعة نفسها بتصميمين: ثلاثة إيصالات مقابل إيصال واحد

حذف التجربة Cleanup

docker compose down -v
docker rmi sw3-wh-app:1

تشغيل نقطة الاستقبال في الإنتاج Operations

بعد أن تعمل النقطة يبقى عمل يومي صغير يحدد هل سوف تكتشف المشكلة في دقيقة أم بعد أن يتصل بك العملاء. والأشياء التي تستحق المراقبة قليلة وواضحة:

  • عدد الرسائل غير المعالجة وعمر أقدمها: إذا توقف العامل فالنقطة تستمر في الرد بنجاح والرسائل تتراكم بصمت، والمرسل لا يرى أي خطأ، لذلك هذا هو أهم مقياس على الإطلاق، وتنبه إذا تجاوز عمر أقدم رسالة خمس دقائق مثلاً.
  • نسبة الرفض بالتوقيع: رسالة مزورة بين حين وآخر شيء طبيعي على عنوان عام، أما إذا ارتفعت النسبة إلى 100% فجأة فالسبب في الغالب سر تغير عند المرسل ولم يتغير عندك، أو تحديث في إطار العمل صار يعدل الجسم، أو ساعة السيرفر انحرفت.
  • زمن الرد p99: يجب أن يبقى بعيداً جداً عن مهلة المرسل، فإذا اقترب منها فسوف تبدأ إعادة المحاولة والتكرار حتى لو كان كل شيء آخر سليماً.
  • سجل التسليمات عند المرسل: GitHub وStripe يعرضان كل محاولة ورمز ردها، وهذا أول مكان تنظر فيه عندما يقول لك أحد إن «الحدث لم يصل».

وتغيير السر Secret Rotation يحتاج ترتيباً حتى لا تضيع رسائل في المنتصف: اطلب من المرسل سراً جديداً مع إبقاء القديم فعالاً، كما يسمح Stripe لمدة تصل إلى سبعة أيام، فيرسل توقيعين مع كل رسالة، ثم ضع السر الجديد عندك بجانب القديم، ثم احذف القديم من عندك، ثم ألغه عند المرسل. ولاحظ أن الدالة verify في التجربة تقبل أي توقيع مطابق من التوقيعات المرسلة، ولكي تقبل سرين يكفي أن تجرب السرين بالترتيب. وغير السر فوراً إذا ظهر في سجل أو مستودع، وقد شرحنا كيف تكتشف ذلك في اكتشاف الأسرار المسربة.

وأخيراً، لا تجعل نقطة الاستقبال تشارك التطبيق الرئيسي في كل شيء إذا كانت الرسائل كثيرة: موجة من آلاف الرسائل في أول الشهر يجب ألا تبطئ صفحات العملاء، لذلك يفصلها البعض في عملية Process خاصة أو خلف مسار مستقل في الـ Reverse Proxy بحدود اتصالات خاصة به، فتبقى المشكلة في مكانها إذا حدثت.

كيف تختبر Webhooks على جهازك؟

المشكلة الأولى في التطوير أن المرسل الحقيقي لا يستطيع الوصول إلى localhost على جهازك، وأمامك ثلاث طرق. الأولى أداة المنصة نفسها إن وجدت، مثل أمر stripe listen --forward-to localhost:4242/webhook الذي يستقبل الأحداث من حسابك التجريبي ويمررها إلى جهازك ويطبع السر الذي توقع به. والثانية نفق Tunnel يعطيك عنوان HTTPS عاماً مؤقتاً يصل إلى جهازك، وقد شرحنا فكرته وأدواته في ما هو النفق Tunnel، ولا تنس أن تغلقه بعد الاختبار لأن عنوانه عام. والثالثة، وهي الأهم للاختبارات الآلية، أن توقع الرسائل بنفسك في الاختبار بالسر التجريبي كما فعلنا في التجربة، فتختبر كل الحالات: التوقيع الخاطئ، والطابع القديم، والمعرف المكرر، والترتيب المعكوس، دون أي اتصال خارجي. وإذا كانت المنصة تحفظ سجلاً بكل التسليمات فاحفظ عدة رسائل حقيقية منها واستخدمها كنماذج في اختباراتك، فهي أصدق من أي رسالة تكتبها يدوياً.

أخطاء شائعة Common Mistakes

  • التحقق على JSON بعد تحويله: تحقق دائماً على البايتات الخام كما وصلت، ثم حولها.
  • المقارنة بـ ==: استخدم مقارنة ثابتة الزمن مثل hmac.compare_digest أو crypto.timingSafeEqual.
  • عدم فحص الطابع الزمني، أو مهلة صفر: توثيق Stripe ينبه إلى أن مهلة 0 في مكتبته تلغي الفحص كلياً ولا تجعله صارماً.
  • العمل الثقيل داخل الطلب: سوف تنتهي مهلة المرسل يوماً، وسوف يتكرر العمل.
  • الرد بخطأ على التكرار: المعرف المكرر يرد عليه بنجاح دون تنفيذ، وإلا أعاد المرسل المحاولة أياماً.
  • الاعتماد على الترتيب: استخدم رقم التسلسل، أو اقرأ الحالة الحالية من الواجهة.
  • السر في العنوان أو في المستودع: السر مكانه مدير الأسرار، وقد شرحنا الخيارات في إدارة الأسرار Secrets Manager.
  • تسجيل الرسالة كاملة في السجلات: الرسالة فيها بيانات عملاء، ومع التوقيع والطابع تصبح جاهزة لإعادة الإرسال خلال النافذة.
  • إذا كنت المرسل: إعادة المحاولة فوراً وبلا عشوائية: سوف تسقط سيرفر العميل لحظة عودته بموجة من كل الرسائل المتراكمة.
  • إذا كنت المرسل: إرسال الطلب إلى أي عنوان يكتبه العميل: احسم الاسم وارفض العناوين الخاصة، وإلا صار سيرفرك أداة لمسح شبكتك الداخلية.

قائمة تحقق Checklist

للمستقبل:

  • نقطة الاستقبال HTTPS، وتقبل POST فقط، ومستثناة من حماية CSRF في إطار العمل.
  • التحقق من التوقيع على النص الخام بمقارنة ثابتة الزمن، ويقبل أكثر من توقيع أثناء تغيير السر.
  • فحص الطابع الزمني بنافذة خمس دقائق، والساعة مضبوطة بـ NTP.
  • حفظ الرسالة في جدول الوارد بمفتاح هو معرفها، والرد بـ 2xx خلال أقل من ثانية.
  • العامل يعالج الرسائل بقفل لا يسمح لعاملين بأخذ الرسالة نفسها، ويعيد المحاولة عند الفشل.
  • التكرار يرد عليه بنجاح، والعمليات المالية لها قيد فريد على مستوى العمل أيضاً.
  • الترتيب يحمى برقم تسلسل أو بقراءة الحالة الحالية.
  • مهمة مصالحة دورية تقارن الحالة مع واجهة المرسل.
  • مراقبة لعدد الرسائل غير المعالجة في جدول الوارد وعمر أقدمها.

للمرسل:

  • رسالة بالشكل الذي تحدده المواصفة: معرف ثابت، وطابع زمني، وتوقيع، ونوع حدث واضح.
  • إعادة محاولة أسية مع عشوائية لمدة أيام، ومهلة بين 15 و30 ثانية.
  • عدم تتبع إعادة التوجيه، والتوقف عند 410، والتخفيف عند 429 و502 و504.
  • طابور لكل نقطة استقبال، وتعطيل النقطة التي تفشل أياماً مع إبلاغ صاحبها.
  • سجل تسليمات يراه العميل، وزر إعادة إرسال.
  • حماية من SSRF: حسم الاسم ورفض العناوين الخاصة والمحلية، والإرسال من شبكة معزولة.
  • تغيير السر دون توقف، بتوقيعين خلال فترة الانتقال.

ماذا تقرأ بعد ذلك؟ Next Steps

الـ Webhook يجعل الأنظمة تتحدث في اللحظة نفسها، والخطوة التالية في هذه المرحلة هي التخزين المؤقت وتحديد معدل الطلبات، أما إذا أردت أن تعرف كيف يعالج العامل الرسائل خارج الطلب بالتفصيل فاقرأ عن المهام الخلفية وإعادة المحاولة وطابور الرسائل الميتة:

دليلكيف تصمم API يبقى متوافقاً مع عملائه بعد سنةمبادئ تصميم API يتطور دون أن يعطل التطبيقات التي تعتمد عليه، وكيف تختار الشكل المناسب لنظامك.دليلزمن الاستجابة Latency والإنتاجية Throughput بالأرقامالأرقام التي يحتاجها كل تصميم من الذاكرة إلى القارات، مقاسة على جهاز واحد، مع الذيل Tail Latency وقانون Little واختبار k6 يبين أين تنهار الخدمة.دليلالمهام الخلفية Background Jobs: لماذا لا ينتظر المستخدم؟كيف تخرج إرسال البريد ومعالجة الملفات من الطلب إلى عامل يعمل في الخلفية، مع تجربة على Celery وRedis تقيس زمن الطلب قبل وبعد وتقتل العامل في منتصف مهمة.دليلإعادة المحاولة Retry وDead Letter Queue وPoison Messageكيف تكتب سياسة إعادة محاولة في الطابور لا تملأ ال Dead Letter Queue برسائل سليمة ولا تغرق خدمة متعبة، بسبع سياسات شغلناها على RabbitMQ وSQS أمام نفس العطل.دليلIdempotency: كيف تجعل العملية آمنة عند تكرارهالماذا تصل الرسالة نفسها أكثر من مرة، وكيف تكتب مستهلكاً يطبقها مرة واحدة فقط مهما تكررت.

الخلاصة Summary

وصلنا لنهاية الموضوع، وأهم ما فيه:

  • الـ Webhook طلب HTTP يرسله النظام الذي وقع عنده الحدث إلى عنوان سجلته، فتعرف فوراً بدل أن تسأل كل دقيقة، وثمنه أنك يجب أن تتعامل مع رسائل مكررة ومتأخرة وبغير ترتيبها ومزورة.
  • التحقق بالـ HMAC على البايتات الخام، بمقارنة ثابتة الزمن، ومع طابع زمني داخل التوقيع، وفي التجربة رفضت رسالة صحيحة فيها نص عربي لأن الكود أعاد بناء JSON قبل التحقق.
  • معرف الرسالة يحميك من التكرار البريء ومن إعادة الإرسال خلال النافذة، والطابع الزمني يحميك بعدها.
  • العمل داخل الطلب مع مهلة خمس ثوان أنتج ثلاثة إيصالات لدفعة واحدة، وجدول الوارد مع عامل منفصل رد في 0.23 ثانية وأنتج إيصالاً واحداً.
  • رقم التسلسل منع رسالة قديمة من إعادة الطلب إلى حالة سابقة.
  • إذا كنت المرسل فإعادة المحاولة الأسية مع العشوائية أنقذت رسالة أرسلت إلى سيرفر متوقف، ولا تنس حماية سيرفرك من العناوين التي يكتبها عملاؤك.

سجل التحديثات Changelog

  • 18 نوفمبر 2026: كتابة المقال، وتنفيذ التجربة على Docker Engine 29.8.0 مع Python 3.13.18 وFastAPI 0.163.2 وuvicorn 0.54.0 وhttpx 0.28.1 وpsycopg 3.3.9 وstandardwebhooks 1.3.0 وPostgreSQL 18.6.
نشرة عرب رووت | ArabRoot

معرفة تستحق مكاناً في بريدك.

مقالات مختارة وأدوات مفيدة وأفكار لمشروعك القادم، في رسالة واحدة كل أسبوع.

يمكنك إلغاء الاشتراك متى شئت. الخصوصية

تم استلام طلبك. افتح بريدك واضغط رابط التأكيد لإتمام الاشتراك.