اشتراكات الإشعارات وإرسالها

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

إدارة الاشتراك

استخدم GET /api/v1/webhooks وPOST /api/v1/webhooks وDELETE /api/v1/webhooks/{id} مع صلاحية webhooks:manage. يقبل الإنشاء حدثًا معلنًا في الإصدار المثبت وعنوان HTTPS. يرتبط الاشتراك بالإصدار المراجع وصلاحية الربط الحالية. إعادة إنشاء الاشتراك لنفس التطبيق والحدث والعنوان تغير مفتاح التوقيع وتعيد تفعيله.

مفتاح التوقيع

تعيد استجابة الإنشاء data.signing_secret مرة واحدة، مع آخر أربعة أحرف منه. احفظه بأمان فورًا؛ تعرض القوائم لاحقًا secret_last_four فقط. عند تغيير المفتاح، حدّث مستقبل الإشعارات بصورة متناسقة.

محتوى الرسالة والتحقق

يتكون جسم JSON من id وtype وoccurred_at وdata. تُرسل الترويسات X-Saas-Event-Id وX-Saas-Timestamp وX-Saas-Signature. يستخدم التوقيع HMAC-SHA256 بصيغة v1=<hex> للنص:

<timestamp>.<event_id>.<exact_request_body>

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

الاتصال وإعادة المحاولة

يلزم HTTPS وعنوان عام. تُرفض العناوين الخاصة والمحلية والمحجوزة، ويُثبّت عنوان الشبكة الذي جرى التحقق منه بعد فحص DNS. لا يتبع المرسل إعادة التوجيه. مهلة الطلب ١٥ ثانية، وللأحداث العادية ست محاولات كحد أقصى مع تأخير متزايد ومحدود.

عقد أحداث الموارد

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

يحتوي data على schema_version: 1 وstore_id وresource. يحتوي المورد على type وid، ويضيف المخزون product_id وvariant_id القابل للقيمة الفارغة وlocation_id. يضيف إشعار الإلغاء app_id. لا تتضمن الرسائل أسماء أو بيانات اتصال أو عناوين أو بيانات دفع أو كميات أو صفوف قاعدة البيانات كاملة. قراءة التفاصيل تحتاج صلاحية قراءة عاملة وموافقًا عليها بصورة مستقلة؛ وجود الحدث لا يفعّل واجهة مخططة وغير منفذة. وقد يكون المورد محذوفًا عند محاولة قراءته.

الإشعار الأخير عند إلغاء الربط

يمكن لاشتراك app.uninstalled المراجع استقبال إشعار أخير عن إلغاء ربط التطبيق نفسه. تُلغى أولًا صلاحية الرموز والاشتراكات والإرسالات العادية. يستخدم الإشعار الاشتراك السابق نفسه، وتنتهي صلاحيته بعد خمس دقائق، وله ثلاث محاولات بحد أقصى وبين المحاولات ٣٠ ثانية. لا يمنح وصولًا جديدًا للقراءة. إعادة الربط أو تغيير العنوان أو المفتاح أو التعليق أو إلغاء الصلاحية أو إيقاف الميزة يلغي الإشعارات المعلقة نهائيًا؛ إعادة التفعيل لا تعيدها. وصول هذا الإشعار غير مضمون عند فشل الشبكة أو انتهاء المهلة.

إلغاء الصلاحيات أثناء الإرسال

تحفظ الإرسالات هوية الاشتراك وإصدار صلاحية الربط. يتحقق السماح بالإرسال مرة واحدة بعد فحص DNS، وتحتاج تسوية النتيجة إلى المطالبة الحالية غير المنتهية. يمكن منع الطلب قبل السماح بإرساله؛ أما الطلب الذي سُمح له وخرج إلى الشبكة فلا يمكن استرجاعه. يجب أن يتحمل المستقبل التكرار ويتوقف عن التصرف نيابة عن المتجر بعد إلغاء التفويض.