الإصدارات والتوافق

كيف تُرقَّم إصدارات حمولات الويب هوك، وما معنى كل معرّف وكل طابع زمني، وكيف يُعلَن عن التغييرات والإيقاف التدريجي

لا تغيّر MailLand حمولات الويب هوك إلا بطرق يستطيع المستقبِل الحالي تجاهلها. تشرح هذه الصفحة هذا الالتزام، والمعرّفات والطوابع الزمنية التي يمكن للمستقبِل الاعتماد عليها، وما يحدث قبل أن يُطرح أي تغيير غير متوافق.

إصدار المخطط

لكل نوع حدث إصدار مخطط لحمولته، وهو عدد صحيح موجب. جميع الأحداث اليوم في الإصدار 1.

يحمله جسم الطلب في الحقل schema_version.
ويحمل الترويسة X-MLND-Event-Version القيمة نفسها.
الجسم الذي لا يحتوي على schema_version (أُرسل قبل وجود الحقل) هو من الإصدار 1.

يُثبَّت الإصدار عند إنشاء الحدث، لذلك تحمل كل إعادة محاولة للحدث نفسه الإصدار نفسه. أما v1 داخل X-MLND-Signature فهو إصدار مخطط التوقيع، وهو مستقل عنه.

المعرّفات

المعرّف	أين	ثابت بين المحاولات	استخدمه من أجل
`event_id`	الجسم، `X-MLND-Event-Id`	نعم	إزالة التكرار: عالِج كل `event_id` مرة واحدة
`event`	الجسم، `X-MLND-Event`	نعم	نوع الحدث، مثل `message.delivered`
`id` المرفق (`inbound.received`)	الجسم، `data.email.attachments[]`	نعم	التعرّف على مرفق نزّلته من قبل؛ `download_url` جديد في كل محاولة
معرّف التسليم	`X-MLND-Delivery-Id`	لا، جديد في كل محاولة	الدعم والتشخيص؛ وهو `publicId` الذي يعرضه سجل التسليمات لتلك المحاولة
`X-MLND-Attempt`	ترويسة	لا	رقم المحاولة، يبدأ من 1

أزل التكرار بالاعتماد على event_id، ولا تعتمد أبدًا على معرّف التسليم. قد تصل الأحداث أكثر من مرة وبترتيب مختلف؛ رتّب أحداث الرسائل حسب data.status_version الذي لا يزداد إلا صعودًا للرسالة الواحدة.

الطوابع الزمنية

الحقل	المعنى
`occurred_at` (الجسم)	وقت وقوع الحدث نفسه. في أحداث الرسائل هو وقت الحدث على خادم البريد، أي اللحظة نفسها في `data.timestamp`.
`timestamp` (الجسم)	وقت إنشاء MailLand لحدث الويب هوك. لم يتغير عن الإصدارات السابقة.
`t` في `X-MLND-Signature`، و`X-MLND-Delivery-Timestamp`	وقت إرسال هذه المحاولة بثواني Unix. يحمل الاثنان القيمة نفسها دائمًا.

جميع الأوقات في الجسم بتوقيت UTC وبصيغة ISO 8601 تنتهي بـ Z. الجسم متطابق في كل محاولة، ولا يتغير إلا ترويسات المحاولة. يغطي التوقيع t والجسم الخام فقط، لا بقية الترويسات؛ فتعامل معها كبيانات توجيه وثِق بالجسم.

التزام التوافق

يجب على المستقبِلين تجاهل حقول JSON وترويسات HTTP التي لا يعرفونها. وبهذه القاعدة يكون كل تغيير مما يلي آمنًا ويتم دون إصدار مخطط جديد:

إضافة حقل إلى الجسم أو إلى data، أو إضافة ترويسة جديدة؛
إضافة نوع حدث جديد لا تتلقاه إلا بعد الاشتراك فيه؛
إضافة قيمة إلى حقل تصفه هذه الوثائق بأنه مفتوح.

وكل تغيير مما يلي غير متوافق ولا يُطبَّق أبدًا على إصدار قائم:

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

لا يُطرح التغيير غير المتوافق إلا في إصدار مخطط جديد تختاره أنت صراحةً. ولا تُنقل الاشتراكات القائمة إلى إصدار جديد تلقائيًا أبدًا.

سياسة الإيقاف التدريجي

يُعلَن عن الإيقاف التدريجي قبل 180 يومًا على الأقل من طلب أي ترحيل: في سجل التغييرات، وفي لوحة التحكم، وبالبريد الإلكتروني إلى مالكي الحساب.
يحدد الإعلان الحدث أو الإصدار أو الحقل بدقة، وبديله، وطريقة الترحيل.
يبقى الحقل الموقوف تدريجيًا في الحمولة، ويبقى الحدث الموقوف تدريجيًا متاحًا للمشتركين الحاليين. الإيقاف التدريجي وحده لا يحذف شيئًا أبدًا. وحذف إصدار ما يتطلب إعلانًا مستقلًا، بعد 180 يومًا على الأقل من إشعار الإيقاف التدريجي.

الاستثناءات

inbound.received يستخدم هذا الغلاف أيضًا. فرق واحد: يُوقَّع download_url لكل مرفق في كل محاولة، لذا يختلف بين إعادة المحاولات؛ أما id المرفق فلا يتغيّر.

خطوات Webhook في الأتمتة ترسل جسمًا مسطحًا بحقول المشترك، لا هذا الغلاف. ومنذ هذا الإصدار تضيف event_id وoccurred_at وschema_version، وتكون موقَّعة. انظر أدناه.

خطوات Webhook في الأتمتة

تُوقَّع خطوات Webhook في الأتمتة تمامًا مثل ويب هوك العملاء: تحقّق من X-MLND-Signature باستخدام سر التوقيع الخاص بمستقبِل تلك الخطوة، وباتباع الخطوات نفسها.

لكل مستقبِل (عنوان URL مختلف لخطوة) سر خاص به، فلا يستطيع أي مستقبِل إنتاج توقيعات يقبلها مستقبِل آخر. الخطوات التي ترسل إلى عنوان URL نفسه مستقبِل واحد وتتشارك سره.
اقرأ الأسرار عبر GET /v1/marketing/automations/{id}/webhook-signing-secrets: قائمة secrets من { webhookUrl, secret } بترتيب الخطوات. تُنشأ عند إنشاء أتمتة تحتوي على خطوة Webhook أو حفظها. يحتفظ التعديل بسر كل عنوان URL لم يتغيّر، ويحصل العنوان الجديد أو المعدَّل على سر جديد.
استبدلها عبر POST /v1/marketing/automations/{id}/webhook-signing-secrets/regenerate الذي يمنح كل مستقبِل سرًا جديدًا ويعيدها. تتوقف الأسرار القديمة فورًا، لذا اجعل كل مستقبِل يقبل السرّين أولًا. نسخة الأتمتة تحصل على أسرار خاصة بها، والأتمتة التي تُحذف كل خطوات Webhook فيها تفقد أسرارها.
لتدوير مستقبِل واحد فقط، أرسل { "webhookUrl": "<عنوان الخطوة>" } في جسم طلب regenerate؛ ويحتفظ كل مستقبِل آخر بسره. العنوان الذي ليس عنوان خطوة Webhook في الأتمتة يُرجع 400.
الأتمتة التي لا يزال مستقبِلوها يتشاركون سرًا واحدًا تُقسَّم إلى أسرار لكل مستقبِل عند تفعيلها أو استئنافها، أو قبل إرسال خطوة Webhook التالية. لا يُوقَّع أي طلب أبدًا بسر يملكه مستقبِل آخر: إذا تعذّر التقسيم فلا تُرسَل الخطوة.
X-MLND-Event-Id ثابت لتنفيذ واحد لخطوة واحدة لمشترك واحد. استخدمه مع نافذة الدقائق الخمس على t لرفض إعادة الإرسال الخبيثة.
الأتمتة التي حُفظت قبل وجود التوقيع ترسل طلبات غير موقَّعة إلى أن تُحفظ من جديد أو يُعاد إنشاء سرها.
هذه الطلبات بأفضل جهد: محاولة واحدة دون جدول إعادة محاولات. وتستمر الأتمتة أيًّا كان رد المستقبِل.

الإصدارات والتوافق

إصدار المخططنسخ رابط القسم

المعرّفاتنسخ رابط القسم

الطوابع الزمنيةنسخ رابط القسم

التزام التوافقنسخ رابط القسم

سياسة الإيقاف التدريجينسخ رابط القسم

الاستثناءاتنسخ رابط القسم

خطوات Webhook في الأتمتةنسخ رابط القسم