استخدم Webhooks للتغييرات المعتادة واحتفظ باستعلامات الحالة لمطابقة سجلاتك مع اللوحة. إذا لم تجهّز مستقبِلًا عامًا موثوقًا، ابدأ بالاستعلام على دفعات.
قد يكتمل طلب أثناء إعادة تشغيل التطبيق، وقد يصل الحدث مرتين إذا ضاعت استجابة التأكيد. يجب التعامل مع الحالتين دون عرض معلومات قديمة أو تطبيق التحديث مرتين.
مهمة واضحة لكل طريقة
- الاستعلام الدوري: معرفة الوضع الحالي
- تعيد action=status الحالة وقت الاستعلام. اجمع حتى 100 معرّف في الطلب. تقصير الفاصل يزيد الطلبات، حتى عندما لا يتغيّر شيء.
- Webhooks: استقبال التغييرات المختارة
- يرسل NotPanel الأحداث إلى عنوان HTTPS المسجّل. لا تستهلك حصة طلبات status لدى العميل، لكن المستقبِل يحتاج سعة ومراقبة.
- المطابقة: استعادة المعلومات المفقودة
- بعد عطل أو عند وجود سجل قديم، استعلم عن الطلبات المعنية. قد تفوت أحداث، والمحاولات محدودة، ووقت الوصول غير مضمون.
ما الذي ترسله API من NotPanel؟
يغطي الدليل نقاط الاستقبال المسجّلة عبر webhook.add: عنوان HTTPS عام وأحداث مدعومة مثل order.processing وorder.in_progress وorder.completed وorder.partial وorder.refunded وorder.refill_completed. احفظ secret؛ لا تعيده webhook.list. افحص الحالة والأخطاء عبر webhook.list واحذف التسجيل عبر webhook.remove.
تحتوي تسليمات API على مصفوفة events حتى عند وجود حدث واحد. لكل عنصر id وevent وtimestamp وdata؛ ويعرّف deliveryId التسليم. المثال المختصر توضيحي، وأوقاته القديمة لا تصلح لاختبار سماحية الوقت.
{
"events": [
{
"id": "EXAMPLE_EVENT_ID",
"event": "order.completed",
"timestamp": 1700000000,
"data": { "order": 7001, "status_key": "completed" }
}
],
"timestamp": 1700000001,
"deliveryId": "EXAMPLE_DELIVERY_ID"
}اقرأ اسم الحدث من الجسم المتحقق منه؛ لا تحتاج دفعات API إلى X-Webhook-Event. تستخدم Webhooks المنشأة في dashboard صيغة مختلفة بحدث واحد؛ الصيغتان ليستا قابلتين للتبادل.
تحقق من توقيع الجسم الأصلي ومن طابعه الزمني.
احفظ التسليم المتحقق منه قبل إرسال استجابة 2xx.
طبّق كل حدث مرة واحدة واستعد المعلومات المفقودة باستعلامات الحالة.
استقبل الأحداث بأمان
- احتفظ بالجسم الأصلي. تحقّق من X-Webhook-Signature باستخدام secret وX-Webhook-Timestamp ثم طبّق سماحية الوقت التي تختارها. إعادة بناء الجسم قد تغيّر البايتات الموقّعة.
- طابق X-Webhook-Delivery-Id مع deliveryId في الجسم الموقّع. احفظ التسليم قبل الرد بـ 2xx؛ إن تعذر قبوله بأمان، اسمح للمرسل بإعادة المحاولة.
- عالِج كل events[].id مرة واحدة. احتفظ بتتبّع التكرار بعد إعادة التشغيل مع تحديث الطلب. قد يصل الحدث نفسه عبر نقاط استقبال متعددة.
- نفّذ العمل البطيء بعد القبول. يثبت التوقيع الأصالة لا ترتيب الوصول. إذا تعارض حدث متأخر مع حالة أحدث، استعلم عبر status قبل استبدالها.
عندما تكون نقطة الاستقبال غير متاحة
تُعد المهلة أو الاستجابة خارج 2xx فشلًا. يعيد NotPanel المحاولة بفواصل متزايدة ويوقف نقطة API مؤقتًا بعد 10 إخفاقات متتالية؛ ويصفّر النجاح العداد. راقب webhook.list: الصمت لا يثبت عدم حدوث تغييرات.
طابق دوريًا الطلبات غير المحسومة أو القديمة بدفعات حتى 100 معرّف مع احترام الرؤوس والحدود. بعد إصلاح نقطة موقوفة، تأكد أن التسجيل active. لا تفترض إعادة إرسال كل التسليمات القديمة الفاشلة تلقائيًا.
اختبر أكثر من تسليم ناجح
استخدم رسائل اصطناعية وsecret خاصًا باختباراتك؛ لا تحتاج طلبات عملاء حقيقية.
- إرسال التسليم نفسه مرتين يجب أن ينتج تحديثًا واحدًا.
- وصول الحدث في دفعتين ثم إعادة التشغيل يجب ألا يكرّره.
- تغيير بايت أو استخدام وقت قديم يجب أن يُرفض حسب سياستك.
- بعد عطل وحدث متأخر، يجب أن يعيد status العرض الحالي.
اختيار الأحداث والتحقق من الأسرار والتأكيد السريع مذكورة أيضًا في إرشادات GitHub حول Webhooks. الرؤوس والصيغ وحدود المحاولات هنا تخص عقد NotPanel.
أسئلة شائعة
هل يمكن استخدام الاستعلام الدوري فقط؟
نعم. اجمع الاستعلامات واختر الفاصل وفق الحجم والحدود. Webhooks ليست إلزامية لإنشاء الطلبات أو تتبّعها.
هل تصل Webhooks فورًا ومرة واحدة فقط؟
لا. قد تتأخر أو تتكرر. تحقّق من كل تسليم، وعالِج الحدث مرة واحدة، واحتفظ باستعلام الحالة للاستعادة.
ما الرؤوس التي يجب فحصها؟
افحص X-Webhook-Signature وX-Webhook-Timestamp، ثم طابق X-Webhook-Delivery-Id مع deliveryId في الجسم المتحقق منه وعالِج مصفوفة events.
هل تحمي Webhooks طلب add غير المؤكد؟
هما مشكلتان مختلفتان. أعد add باستخدام request_id الأصلي ومعلمات دون تغيير، ثم احفظ معرّف الطلب المستعاد.
مراجع: عقد Webhooks · حالة الطلب · الاستعادة بعد المهلة.
