الـ Webhooks في زد: الاشتراك، ومتابعة الصحة، واستعادة الروابط المعطّلة

لماذا الـ Webhooks؟

تتيح الـ Webhooks لزد أن تُبلغ تطبيقك فور وقوع حدث في المتجر، مثل طلب جديد أو تحديث منتج أو تسجيل دخول عميل، فلا تحتاج إلى سؤال الـ API مرة بعد مرة. وهذا مهم لأن زد تسمح بـ 60 طلبًا في الدقيقة لكل تطبيق في كل متجر، وتطلب صراحة ألا تستعلم باستمرار عن حالة الطلبات أو الدفع.

الأحداث نوعان:

• أحداث المتجر (الطلبات، المنتجات، السلال المتروكة، العملاء، التصنيفات): تشترك فيها لكل متجر عبر Merchant API.
• أحداث اشتراك التطبيق، مثل app.market.application.install وapp.market.subscription.active وapp.market.application.uninstall: تضبطها من قسم Webhooks في صفحة تطبيقك بلوحة الشركاء، مع رابط الاستقبال و Headers إضافية إن احتجت.

أحداث المتجر المتاحة

• الطلبات: order.create وorder.status.update وorder.payment_status.update
• المنتجات: product.create وproduct.update وproduct.publish وproduct.delete
• السلال المتروكة: abandoned_cart.created وabandoned_cart.completed
• العملاء: customer.create وcustomer.update وcustomer.merchant.update وcustomer.login
• التصنيفات: category.create وcategory.update وcategory.delete

يقبل الحدثان order.create وorder.status.update شروطًا (conditions) تصفّي الأحداث فلا يصلك إلا ما يهمك. المفاتيح المدعومة هي delivery_option_id وstatus وpayment_method:

{
  "conditions": {
    "delivery_option_id": "55",
    "payment_method": "Cash On Delivery"
  }
}

تحتاج حدثًا أو شرطًا غير متوفر بعد؟ ترحّب زد باقتراحاتك عبر دعم سوق التطبيقات.

إنشاء الاشتراكات وعرضها وحذفها

كل نقاط الـ Webhooks تتطلب الـ Headers Authorization وX-Manager-Token. الإنشاء والحذف يحتاجان الصلاحية third_webhook_write، والعرض يحتاج third_webhook_read.

POST   /v1/managers/webhooks
GET    /v1/managers/webhooks
DELETE /v1/managers/webhooks?original_id=2404

• الإنشاء يتطلب event وtarget_url وoriginal_id، أما conditions وusername وpassword فاختيارية.
• العرض يعيد الـ Webhooks التي اشترك فيها تطبيقك لذلك المتجر.
• الحذف يزيل الـ webhook عبر original_id. أما نقطة الحذف القديمة حسب المشترك (subscriber) فمعلَّمة كمتوقفة (deprecated).

إذا حدّدت username وpassword، ترسل زد كل إشعار مع Header Authorization: Basic تحمل username:password مرمّزة بـ Base64. تحقق منها في الـ Server الخاص بك لتتأكد أن الطلب قادم من زد فعلًا.

كيف يعمل تتبّع الصحة

تراقب زد كل رابط استقبال بنمط circuit breaker، ولكل webhook حقل health_status:

• healthy: الإرسال يتم كالمعتاد.
• degraded: 10 إخفاقات أو أكثر خلال الساعة الماضية. تستمر زد في المحاولة، لكن عليك أن تبحث في السبب.
• broken: 30 إخفاقًا أو أكثر خلال الساعة الماضية. يتوقف الإرسال حتى تستعيد الـ webhook.

تُحسب الإخفاقات في نافذة متحركة مدتها ساعة. الاستجابة بغير 2xx، أو انتهاء مهلة الاتصال، أو أي خطأ مشابه يُعدّ إخفاقًا، وأي إرسال ناجح واحد يصفّر العدّاد ويعيد الحالة إلى healthy. أما الاستجابة 429 فلا تُحتسب إخفاقًا، لأنها تعني أن رابطك يعمل لكنه يحدّ من الطلبات.

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

الـ Webhooks المعطّلة واستعادتها

حين يتعطّل webhook، تتوقف زد عن إرسال أي أحداث جديدة إليه، وتتخلص من الأحداث المعلّقة التي لم تُسلَّم بعد. ويصلك كل ساعة بريد مجمّع بعنوان "Action Required: Your webhook endpoints are failing" ومعه ملف broken_webhooks.csv يسرد كل webhook معطّل ومتجره وحدثه ورابطه وتوقيتات إخفاقه.

يبقى الـ webhook معطّلًا حتى تستعيده عبر الـ API. استخدم GET /v1/managers/webhooks/health-summary لترى عدد الـ Webhooks في كل حالة بسرعة، وGET /v1/managers/webhooks/broken للقائمة الكاملة، ثم نفّذ الاستعادة:

POST /v1/managers/webhooks/broken/recover

{
  "webhooks": [
    {
      "broken_webhook_id": "{{webhook_uuid}}",
      "target_url": "https://your-new-endpoint.example.com/hook"
    }
  ]
}

• يجب أن تقدّم target_url جديدًا. إعادة استخدام الرابط القديم مرفوضة، لأن زد تريد ما يؤكد أنك عالجت المشكلة.
• تحذف زد الـ webhook المعطّل حذفًا ناعمًا (soft-delete)، وتنشئ webhook جديدًا للحدث نفسه يبدأ بعدّاد إخفاقات نظيف.
• النجاح الجزئي مدعوم، فتعثّر عنصر واحد لا يوقف بقية الدفعة.

ممارسات جيدة لرابط الاستقبال

• استخدم HTTPS مع TLS حديث: تتحقق لوحة الشركاء من الروابط، وتتوقع TLS 1.2 أو 1.3، وشهادة صالحة، و Server متاحًا للعامة، ومصافحة TLS تكتمل خلال 5 ثوانٍ.
• أكّد الاستلام بسرعة: أعِد استجابة 2xx فورًا، ونفّذ المعالجة الثقيلة في الخلفية، حتى لا يتحول البطء إلى إخفاقات محسوبة.
• توقّع التكرار: بسبب إعادة المحاولات قد يصلك الحدث نفسه أكثر من مرة، فاجعل معالجتك آمنة عند التكرار.
• استخدم 429 عند الضغط: إن امتلأت طاقتك فاستجابة 429 لا تدفعك نحو حالة broken.
• راقب الصحة باستمرار: استعلم عن ملخص الصحة، وتابع رسائل الإخفاق، وراجع Webhook Logs في لوحة الشركاء، حيث تستطيع عرض عمليات الإرسال وإعادة محاولتها.
• اختبر على متجر تطوير: نفّذ إجراءات حقيقية، وتأكد أن كل حدث مشترك فيه يصل قبل أن ترسل تطبيقك للمراجعة.