Webhooks أم الاستعلام الدوري؟ تتبّع طلبات يستعيد المعلومات المفقودة

استخدم Webhooks للتغييرات المعتادة واحتفظ باستعلامات الحالة لمطابقة سجلاتك مع اللوحة. إذا لم تجهّز مستقبِلًا عامًا موثوقًا، ابدأ بالاستعلام على دفعات.

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

مهمة واضحة لكل طريقة

الاستعلام الدوري: معرفة الوضع الحالي

تعيد action=status الحالة وقت الاستعلام. اجمع حتى 100 معرّف في الطلب. تقصير الفاصل يزيد الطلبات، حتى عندما لا يتغيّر شيء.

Webhooks: استقبال التغييرات المختارة

يرسل NotPanel الأحداث إلى عنوان HTTPS المسجّل. لا تستهلك حصة طلبات status لدى العميل، لكن المستقبِل يحتاج سعة ومراقبة.

المطابقة: استعادة المعلومات المفقودة

بعد عطل أو عند وجود سجل قديم، استعلم عن الطلبات المعنية. قد تفوت أحداث، والمحاولات محدودة، ووقت الوصول غير مضمون.

ما الذي ترسله API من NotPanel؟

أضف نقطة استقبال من صفحة API في dashboard أو عبر webhook.add: عنوان HTTPS عام والأحداث التي تحتاجها، مثل order.processing وorder.in_progress وorder.completed وorder.partial وorder.canceled وorder.cancel_refused وrefill.completed وrefill.rejected؛ ويسرد مرجع Webhooks القائمة كاملة. احفظ secret بأمان: يظهر مرة واحدة فقط، ولا تعيده webhook.list أبدًا. اعرض نقاط الاستقبال عبر webhook.list، وأرسل ping تجريبيًا عبر webhook.test، واحذف نقطة الاستقبال عبر webhook.remove.

يحمل كل تسليم حدثًا واحدًا داخل غلاف قصير: id وtype وschema_version وcreated_at وsequence وdata. يحتوي data.order على الحقول نفسها التي يعيدها action=status. المثال المختصر أدناه يوضح البنية فقط، وليس طلبًا حقيقيًا.

{
  "id": "EXAMPLE_EVENT_ID",
  "type": "order.completed",
  "schema_version": 1,
  "created_at": "2026-10-10T12:30:00Z",
  "sequence": 1042,
  "data": {
    "order": {
      "order": 7001,
      "status": "Completed",
      "status_key": "completed",
      "remains": "0"
    }
  }
}

اقرأ نوع الحدث من الجسم المتحقق منه. يُرسل X-Webhook-Event أيضًا، لكنه غير موقّع. تتلقى نقاط الاستقبال المضافة من dashboard وعبر API الغلاف نفسه.

استقبل الأحداث بأمان

1. احتفظ بالجسم الأصلي. تحقّق من X-Webhook-Signature باستخدام secret وX-Webhook-Timestamp ثم طبّق سماحية الوقت التي تختارها. إعادة بناء الجسم قد تغيّر البايتات الموقّعة.
2. سجّل X-Webhook-Delivery-Id لتتبّع المحاولات؛ فهو ثابت في كل إعادة محاولة لذلك التسليم. احفظ الحدث المتحقق منه قبل الرد بـ 2xx؛ إن تعذر قبوله بأمان، اسمح للمرسل بإعادة المحاولة.
3. عالِج كل id للحدث مرة واحدة. احتفظ بتتبّع التكرار بعد إعادة التشغيل مع تحديث الطلب. يصل id الحدث نفسه إلى كل نقطة استقبال مشتركة في ذلك الحدث.
4. نفّذ العمل البطيء بعد القبول. يثبت التوقيع الأصالة لا ترتيب الوصول. استخدم sequence لترتيب الأحداث، وإذا تعارض حدث متأخر مع حالة أحدث، استعلم عبر status قبل استبدالها.

دليل التحقق من التوقيع

عندما تكون نقطة الاستقبال غير متاحة

تُعد المهلة (10 ثوانٍ) أو الاستجابة خارج 2xx محاولة فاشلة. يحاول NotPanel كل تسليم حتى 8 مرات خلال 24 ساعة: فورًا، ثم بعد 1 دقيقة و5 دقائق و30 دقيقة وساعتين و6 ساعات و12 ساعة و24 ساعة من الحدث. وتُوقف نقطة الاستقبال مؤقتًا بعد 50 إخفاقًا متتاليًا أو 3 أيام دون نجاح، ويُبلَّغ صاحب الحساب. ويصفّر النجاح العداد. راقب webhook.list: الصمت لا يثبت عدم حدوث تغييرات.

طابق دوريًا الطلبات غير المحسومة أو القديمة بدفعات حتى 100 معرّف مع احترام الرؤوس والحدود. بعد إصلاح نقطة الاستقبال، استأنفها من قسم Webhooks في صفحة API داخل dashboard، وهذا يصفّر عداد إخفاقاتها. ويمكنك بدلًا من ذلك حذفها عبر webhook.remove ثم إضافة عنوان HTTPS الذي أصلحته والأحداث المطلوبة عبر webhook.add، وحفظ secret الجديد بأمان وتحديث التحقق في نقطة الاستقبال. لا توفر واجهة API العامة إجراءً لاستئناف نقطة الاستقبال. التسليمات التي كانت في الانتظار عند الإيقاف لا يُعاد إرسالها، لذا طابق حالات الطلبات الفائتة عبر status.

اختبر أكثر من تسليم ناجح

استخدم رسائل اصطناعية وsecret خاصًا باختباراتك؛ لا تحتاج طلبات عملاء حقيقية.

• إرسال التسليم نفسه مرتين يجب أن ينتج تحديثًا واحدًا.
• يجب التعرّف على الحدث نفسه إذا سُلّم مرتين مع إعادة تشغيل بينهما.
• تغيير بايت أو استخدام وقت قديم يجب أن يُرفض حسب سياستك.
• بعد عطل وحدث متأخر، يجب أن يعيد status العرض الحالي.

اختيار الأحداث والتحقق من الأسرار والتأكيد السريع مذكورة أيضًا في إرشادات GitHub حول Webhooks. الرؤوس والصيغ وحدود المحاولات هنا تخص عقد NotPanel.

أسئلة شائعة

هل يمكن استخدام الاستعلام الدوري فقط؟

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

هل تصل Webhooks فورًا ومرة واحدة فقط؟

لا. قد تتأخر أو تتكرر. تحقّق من كل تسليم، وعالِج الحدث مرة واحدة، واحتفظ باستعلام الحالة للاستعادة.

ما الرؤوس التي يجب فحصها؟

افحص X-Webhook-Signature وX-Webhook-Timestamp، ثم اقرأ id وtype وdata من الجسم المتحقق منه. استخدم X-Webhook-Delivery-Id لتتبّع المحاولات فقط.

هل تحمي Webhooks طلب add غير المؤكد؟

هما مشكلتان مختلفتان. أعد add باستخدام request_id الأصلي ومعلمات دون تغيير، ثم احفظ معرّف الطلب المستعاد.

مراجع: عقد Webhooks · حالة الطلب · الاستعادة بعد المهلة.