Webhooks في المتاجر الإلكترونية: كيف يتواصل الدفع والشحن مع متجرك؟

Webhook وAPI وPolling: ما الفرق؟

مثال عملي: الدفع نجح والمتصفح أغلق

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

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

بنية استقبال موثوقة

التسلسل المقترح هو: مزود، ثم endpoint عبر HTTPS، ثم تحقق، ثم صندوق أحداث دائم، ثم استجابة نجاح للاستلام، ثم طابور وعامل معالجة. هذه توصية معمارية، وليست بروتوكولًا موحدًا لكل شركة.

لا ترسل بريدًا ولا تنشئ شحنة ولا تنتظر CRM داخل مسار الاستقبال إذا كان ذلك سيؤخر الرد. سجل الحدث بصورة دائمة وأقر بالاستلام، ثم نفذ الأعمال خلفيًا. نجاح HTTP يعني أنك تحملت مسؤولية الحدث، لا أن كل آثاره اكتملت.

المصدر: Azure: queue-based load leveling

التحقق من التوقيع يسبق الثقة في البيانات

الآلية تختلف بين المزودين: قد تكون توقيعًا على جسم الطلب الخام، أو HMAC لحقول محددة، أو تحققًا خادميًا آخر. نفذ الخوارزمية الموثقة للمزود، ولا تستخدم وصفة شركة مختلفة.

Stripe يتطلب الجسم الخام للتحقق من التوقيع. تغيير البيانات قبل التحقق قد يفسد النتيجة. احفظ أسرار الإنتاج والاختبار منفصلة، وراجع معالجة إعادة الإرسال القديمة وتدوير الأسرار حسب عقد التكامل.

المصدر: Stripe: webhook signatures

التوقيع الصحيح لا يكفي وحده

• طابق حساب التاجر وبيئة الاختبار أو الإنتاج.
• اربط معرّف العملية بمحاولة دفع موجودة وبالطلب الصحيح.
• تحقق من القيمة والعملة ونوع الحدث والحالة الحالية.
• امنع الانتقالات غير المنطقية، مثل تحويل مدفوع إلى انتظار بسبب حدث قديم.
• لا تسمح لحقول عامة داخل الرسالة بأن تنفذ عمليات خارج نطاق التكامل.

منع التكرار على مستوى الحدث والأثر

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

حماية صندوق الأحداث ليست كافية لكل شيء: قد يعبر حدثان مختلفان عن العملية نفسها، أو يتعطل العامل بعد إنشاء شحنة وقبل تسجيل النجاح. استخدم معرّفات ثابتة للآثار الجانبية وقيودًا مناسبة، ومفتاح idempotency عند دعم API له.

لا تفقد الحدث بين قاعدة البيانات والطابور

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

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

الأحداث قد تتأخر أو تصل بترتيب مختلف

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

في الشحن، افصل حالات شركة النقل عن نموذج المتجر: in_transit أو delivered أو delivery_failed. لا تعتبر شحنة قديمة مُسلّمة دليلًا على اكتمال كل بنود طلب متعدد الشحنات.

إعادة المحاولة وDead Letter Queue

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

انقل الأحداث المستنفدة إلى قائمة فشل واضحة مع تنبيه وسبب ومعلومات ارتباط بالطلب. إعادة التشغيل يجب أن تمر بالقواعد نفسها حتى لا تنشئ أثرًا مكررًا. مهل الرد وسياسات retries تختلف بين المزودين؛ لا تفترض رقمًا واحدًا للجميع.

مثال منطقي مبسط للاستقبال

هذا مثال تعليمي للترتيب، وليس endpoint جاهزًا للإنتاج. verify_provider_signature يجب أن يطبق عقد المزود، وinbox وoutbox يجب أن يُحفظا داخل المعاملة نفسها.

event = verify_provider_signature(raw_body, headers, secret)
validate_provider_and_environment(event)

with database.transaction():
    inserted = inbox.insert_if_new(
        provider=event.provider,
        event_id=event.id,
        payload=event
    )
    if inserted:
        outbox.add('process_webhook', event.id)

return HTTP_200

# Worker: validate business data, apply safe transitions,
# retry transient failures, and record processing results.

ما الذي تختبره قبل الإطلاق؟

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

المراقبة والمصالحة جزء من التكامل

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

شغّل مصالحة دورية للمدفوعات والشحنات العالقة مع API المزود. Webhooks وسيلة إشعار مهمة، لكنها لا تغني عن اكتشاف الانقطاع ومراجعة الحقيقة الخارجية وإصلاح التباين.