صحة Webhooks في زد: استعد Endpoints المعطلة دون فقد الطلبات

يوفّر Zid Webhook Health Tracking آلية موثقة تشبه Circuit Breaker لاشتراكات Webhooks. تصنّف زد عنوان الاستقبال إلى Healthy أوDegraded أوBroken وفق إخفاقات التسليم الحديثة. وعندما يصبح الاشتراك Broken يتوقف إرسال الأحداث الجديدة وتُهمل الأحداث المعلّقة التي لم تُسلّم. لذلك لا تكفي استعادة تكامل ERP أومستودع أونظام مدفوعات بتغيير URL فقط؛ يجب استبدال المستقبل بأمان، واستعادة التسليم، ثم مطابقة السجلات المتأثرة من API موثوق.

تم التحقق من وثائق زد الرسمية في 22 أكتوبر 2026. عتبات الحالات ومواعيد Retry والصلاحيات وسلوك الاستعادة حقائق موثقة من المنصة. أما Durable Inbox والتنبيهات وخطوات المطابقة وضوابط الإطلاق فهي توصيات هندسية يجب اختبارها مع تطبيقك وعقد زد الحالي.

ماذا تعني حالات الصحة في زد؟

تشرح وثيقة Webhook Health Tracking ثلاث حالات ضمن نافذة متحركة مدتها ساعة:

يعيد أي تسليم ناجح عدّاد الفشل إلى الصفر ويعيد الحالة Healthy. وتوضح زد أن HTTP 429 لا يدخل ضمن عدّاد فشل الصحة. هذا يمنع اعتبار Receiver متعطلًا لمجرد أنه طلب تخفيف المعدل، لكنه لا يجعل التشبع مقبولًا: تكرار 429 يؤخر حالة الطلبات، ويزيد Backlog، ويستهلك نافذة التشغيل.

توثق زد ثلاث فترات لإعادة المحاولة بعد فشل التسليم: دقيقة، ثم خمس دقائق، ثم خمس عشرة دقيقة. لا يُحتسب الفشل إلا بعد استنفاد التسلسل. لهذا لا تعني Degraded خطأً لحظيًا واحدًا؛ بل تشير إلى عدة عمليات تسليم تجاوزت سياسة Retry. انتظار Broken قبل التنبيه يفوّت نافذة الإصلاح المبكر.

تعيد نقطة Health Summary أعداد Healthy وDegraded وBroken وتتطلب صلاحية third_webhook_read. وتعرض نقطة Broken Webhooks الاشتراكات المعطلة بالصلاحية نفسها، بينما تتطلب عملية الاستعادة third_webhook_write.

لماذا تمثل Broken فجوة بيانات؟

عندما يصبح الاشتراك Broken، تقول الوثائق إن زد توقف إرسال الأحداث الجديدة، وتتخلص من Pending Events غير المسلّمة، ويبقى الاشتراك Broken حتى استعادة صريحة. ويحتفظ السجل القديم بـbroken_at للتدقيق. لا تعيد الاستعادة تشغيل المستقبل نفسه؛ بل تحذف الاشتراك القديم Soft Delete وتنشئ اشتراكًا Healthy جديدًا للأحداث نفسها مع Target URL جديد.

شرط URL الجديد مفيد لأنه يمنع إعادة التوجيه إلى المسار المعطل نفسه من دون تحقق. كما يشجع Route بإصدار واضح مثل /webhooks/zid/v2 أوBlue-Green Hostname. لكن المنصة لا تستطيع إعادة إنشاء أحداث تجارية تم تجاهلها أثناء التعطل. على التكامل تحديد النافذة المتأثرة ومقارنة حالته المحلية بموارد زد الموثوقة.

في تكامل الطلبات، لا تبدأ المطابقة من وقت انتباه المهندس فقط. استخدم أقدم وقت موثوق بين آخر نجاح محلي وbroken_at، ثم أضف Overlap يغطي اختلاف الساعة وتأخر Queue وتأخر الاكتشاف. يكون التداخل آمنًا فقط إذا كانت الكتابات Idempotent.

لهذا توجد عمليتان منفصلتان: استعادة Receiver تعيد الأحداث المستقبلية؛ وReconciliation تصلح الفجوة السابقة؛ وDeduplication تمنع التداخل من تكرار الآثار؛ وAudit Record يثبت الاشتراكات والكيانات التي تم إصلاحها.

يشرح دليل مزامنة Webhooks التي تتحمل الأحداث المفقودة نمط Durable Inbox العام. أما هذا الدليل فيركز على عقد الصحة والاستعادة الصريح في زد.

صمّم Receiver لقبول سريع ودائم

يجب أن يقتصر Request Path على التحقق من المرسل وحفظ الحدث الأصلي ثم إرسال استجابة صحيحة. لا تنفذ تحديث ERP أوإنشاء شحنة أوإرسال رسالة أوإعادة حساب مخزون قبل الإقرار.

مسار استقبال عملي:

1. استقبل الطلب واحتفظ بالبايتات المطلوبة لعقد التحقق؛
2. تحقق من الطلب وفق متطلبات المصادقة الحالية في زد؛
3. استخرج Delivery Identity ثابتة من معرف حدث موثق عندما يتوافر؛
4. خزّن Raw Event والرؤوس الضرورية وهوية الاشتراك ووقت الوصول في Durable Inbox ضمن Transaction واحدة؛
5. أرسل Success فقط بعد Commit؛
6. اترك Worker غير متزامنًا يفك الحمولة ويتحقق منها ويطبق انتقال الحالة.

إذا لم توفر حمولة نوع محدد معرف تسليم فريدًا، أنشئ مفتاح Deduplication محدود العمر من Store ونوع الحدث ومعرف الكيان وSource Version أوTimestamp. لا تستخدم Hash للـJSON كاملًا بلا تفكير؛ اختلاف ترتيب الحقول أوإضافة Property اختيارية قد يحول الحدث التجاري نفسه إلى Hash جديد.

CREATE TABLE zid_webhook_inbox (
  delivery_key text PRIMARY KEY,
  store_id text NOT NULL,
  event_type text NOT NULL,
  entity_id text,
  received_at timestamptz NOT NULL DEFAULT now(),
  payload jsonb NOT NULL,
  status text NOT NULL DEFAULT 'pending',
  attempts integer NOT NULL DEFAULT 0,
  processed_at timestamptz,
  last_error text
);

المفتاح الأساسي بوابة Idempotency وليس ضمانًا لصحة Handler. يجب أن تكون الكتابات اللاحقة Idempotent أيضًا. أمر Refund يحتاج Business Key وحالة مستقلة، وإلا قد يؤدي Replay إلى أثر مالي مكرر.

اعزل Handler عن الاعتماديات البطيئة. إذا تعطلت قاعدة Inbox، فإن إرسال Success يفقد الحدث. لا تقر إلا بعد التخزين الدائم. وإذا فشل العمل اللاحق، أعد المحاولة بسياسة محدودة، وانقل Poison Messages إلى Quarantine ظاهر بدل تعطيل كل الأحداث التالية.

راقب الصحة من دون صنع عطل جديد

استخدم نقاط الصحة كإشارة Control Plane. يستطيع Monitor مجدول قراءة Summary بفاصل معتدل وتخزين انتقالات الحالة. توثق زد حدًا عامًا يبلغ 60 طلبًا في الدقيقة لكل تطبيق لكل متجر في دليل Rate Limiting. لذلك فحص كل خمس دقائق مثال هندسي لا شرط من المنصة، ويجب ضبطه وفق عدد المتاجر وAPI Budget.

راقب أعداد الحالات لكل متجر، وأول وقت دخل فيه الاشتراك حالته، واستمرار Degraded، ونسبة قبول Durable Inbox، وعمر Queue، وأخطاء Workers، وأحدث Source Timestamp مطبق، والزمن منذ آخر Reconciliation ناجحة.

لا تطلق Page عند فشل تسليم واحد والمنصة تعيد محاولته. أطلقه عندما تستمر Degraded، أويفشل حفظ Inbox، أويتجاوز تأخر الحالة هدف الخدمة. أما Broken فيجب أن تنشئ Incident فورًا لأن الوثائق تؤكد توقف الإرسال والتخلص من الأحداث المعلقة.

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

استعد عبر Endpoint بديل بإصدار جديد

جهّز المستقبل البديل قبل استدعاء Recovery. يجب أن يصل URL الجديد إلى حدود Durable Ingestion نفسها عبر Route ذي إصدار أوهدف مستقل. تحقق من TLS وDNS والمصادقة وحدود الحجم وTimeout واتصال قاعدة البيانات وصلاحيات Queue والرصد من شبكة الإنتاج.

مسار استعادة مضبوط:

1. اقرأ Health Summary وBroken List بصلاحية third_webhook_read؛
2. افتح Incident يحوي هوية Hook ونوع الحدث وURL القديم وbroken_at وآخر نجاح محلي؛
3. انشر Target URL جديدًا من دون حذف المسار القديم؛
4. نفّذ Probe داخليًا لا ينتحل تسليمًا من زد؛
5. تحقق من Secrets وStore Mapping؛
6. أرسل Recovery Batch بصلاحية third_webhook_write؛
7. افحص نتيجة كل عنصر لأن زد تدعم Partial Failure؛
8. تأكد أن الاشتراك الجديد Healthy ويقبل كتابة دائمة؛
9. طابق نافذة البيانات المتأثرة؛
10. أوقف المسار القديم فقط بعد اكتمال الدليل.

لا تسجل Access Tokens أوBasic Auth أوحمولات حساسة كاملة داخل Incident. خزّن الأسرار في Secret Manager، وسجل معرفات أوHashes تسمح بالربط من دون كشف بيانات العميل.

DETECTED
  -> REPLACEMENT_READY
  -> RECOVERY_REQUESTED
  -> DELIVERY_VERIFIED
  -> RECONCILING
  -> VERIFIED
  -> CLOSED

Any failed step -> NEEDS_REVIEW

خزّن كل انتقال مع Actor وTimestamp وInput Hash والنتيجة. إذا انتهت مهلة Recovery Request فلا تعِدها فورًا؛ اقرأ الاشتراكات والحالة أولًا للتمييز بين فشل الطلب ونجاحه مع ضياع الاستجابة.

راجع أيضًا تدوير عنوان Webhook بأمان. مبدأ Blue-Green متشابه، لكن استعادة Broken في زد تضيف شرط URL جديدًا وحالة صحة مسجلة عبر API.

طابق الطلبات والكيانات المفقودة

تعيد الاستعادة قناة الأحداث، لكنها لا تثبت تطابق ERP أونظام المستودع مع زد. يجب أن تقرأ Reconciliation الموارد الموثوقة في نافذة الحادث وتقارنها محليًا عبر Stable IDs وSource Versions.

لكل كيان، حمّل التمثيل الموثوق وحالته الحالية، ثم ابحث عن السجل المحلي وآخر Source Version مطبق. أضف المفقود أوطبّق انتقالًا أحدث وصحيحًا. لا تستبدل دليلًا محليًا أحدث بلا مراجعة. أنشئ Downstream Effect فقط إن لم يكتمل Idempotency Key، وسجل النتيجة matched أوrepaired أوconflicted أوfailed.

لا تعِد تشغيل أحداث تاريخية عشوائيًا لإكمال Queue شكليًا. تطبيق “order created” قديم بعد Cancellation حديثة قد يعيد النموذج للخلف. فضّل Current-State Reconciliation واحرس الانتقالات بـSource Version وEvent Time وحواف State Machine المسموح بها.

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

اختم المطابقة بفحوص مجمعة: العدد والقيمة حسب Status وCurrency وFulfillment Location والفترة. قد تخفي مقارنة الصفوف صفحة كاملة أسقطها Pagination Bug؛ وتكشف المقارنة المجمعة الفجوات النظامية.

أفضل الممارسات وما يجب تجنبه

طبّق Least Privilege: المراقبة تحتاج third_webhook_read، والاستعادة تحتاج third_webhook_write. افصل Credential أوRuntime Role كي لا يغيّر Monitor الاشتراكات.

تعامل مع Degraded كنافذة إنذار. افحص أخطاء Receiver وانتهاء الشهادة وتغير المصادقة وتشبع قاعدة البيانات وDeployment Regression بينما يستمر التسليم. اختبر Target البديل، وسجل نتيجة كل عنصر في الدفعة، وطابق المصدر بعد كل Broken Incident.

تجنب إرسال Acknowledgement قبل التخزين الدائم، وتنفيذ ERP داخل Request Thread، واعتبار 429 بلا أثر، والاستعادة إلى URL غير مختبر، واعتبار Healthy دليلًا على اكتمال الماضي، وReplay بلا Version Guards، وتكرار Recovery غير مؤكدة قبل قراءة الحالة، ووضع الأسرار في Logs، وPolling كثيف ينافس أعمال API الفعلية.

تحمي حالات المنصة بنية التسليم، لكنها لا تضمن صحة العمل من البداية إلى النهاية. يظل نظامك مسؤولًا عن Durable Acceptance وIdempotent Effects واكتشاف الفجوة ودليل نجاح الإصلاح.

قائمة إنتاج

قبل الإطلاق، وثق Event Types والمصادقة وملكية Target URL وOn-call Owner. اختبر Signature خاطئة وتسليمًا مكررًا وأحداثًا بترتيب عكسي وتعطل Inbox وفشل Worker وHTTP Timeout وحالة Degraded مستمرة واستعادة Broken مع عنصر فاشل داخل Batch ومطابقة النافذة الدقيقة.

أنشئ Dashboards لحالة المنصة وحالة التطبيق. أبقِ Versioned Replacement Route جاهزًا. قيد Write Scope. خزّن Raw Evidence بسياسة احتفاظ مناسبة. تحقق من كل Downstream Command مستقلًا. وشغّل Reconciliation مجدولة حتى عندما تبدو Webhooks سليمة، لأن نظام تسليم واحدًا لا يثبت تطابق قاعدتي بيانات.

النتيجة المطلوبة ليست مجرد مؤشر أخضر. إنها حلقة استعادة مغلقة: تكشف زد فشل التسليم، ويرفع Monitor الإشارة الصحيحة، ويستعيد Endpoint بديل تم التحقق منه الأحداث المستقبلية، وتصلح Reconciliation الفترة التي أُهملت، ويثبت Audit Evidence اكتمال الطلبات والمدفوعات والتنفيذ بلا آثار مكررة.

للمساعدة في بناء تكاملات تجارة إلكترونية موثوقة، راجع خدمات البرمجيات والتكامل.

إعداد: Noor Yasser