نسخه‌بندی و سازگاری

نسخه‌بندی بدنهٔ وب‌هوک‌ها، معنای هر شناسه و هر زمان، و شیوهٔ اعلام تغییرها و منسوخ‌شدن‌ها

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`	هدر	خیر	شمارهٔ تلاش، از ۱

یکتاسازی را با event_id انجام دهید، نه با شناسهٔ تحویل. رویدادها ممکن است بیش از یک‌بار و بی‌ترتیب برسند؛ رویدادهای پیام را بر پایهٔ data.status_version مرتب کنید که برای هر پیام فقط افزایش می‌یابد.

زمان‌ها

فیلد	معنا
`occurred_at` (بدنه)	زمان رخ‌دادن خود رویداد. در رویدادهای پیام، زمان رویداد روی سرور ایمیل است؛ همان لحظهٔ `data.timestamp`.
`timestamp` (بدنه)	زمانی که MailLand رویداد وب‌هوک را ساخت. نسبت به نسخه‌های پیشین تغییری نکرده است.
`t` در `X-MLND-Signature` و `X-MLND-Delivery-Timestamp`	زمان فرستادن همین تلاش، به ثانیهٔ یونیکس. این دو همیشه یک مقدار دارند.

همهٔ زمان‌های بدنه به وقت UTC و در قالب ISO 8601 با Z پایانی‌اند. بدنه در هر تلاش یکسان است و فقط هدرهای هر تلاش تغییر می‌کند. امضا فقط t و بدنهٔ خام را پوشش می‌دهد، نه هدرهای دیگر را؛ پس آن‌ها را فرادادهٔ مسیریابی بدانید و به بدنه اعتماد کنید.

تعهد سازگاری

گیرنده‌ها باید فیلدهای JSON و هدرهای HTTP ناشناخته را نادیده بگیرند. با این قاعده، هر تغییر زیر بی‌خطر است و بدون نسخهٔ طرح‌وارهٔ تازه انجام می‌شود:

افزودن فیلد به بدنه یا به data، یا افزودن هدر تازه؛
افزودن نوع رویداد تازه که فقط پس از اشتراک دریافت می‌کنید؛
افزودن مقدار تازه به فیلدی که این مستندات آن را باز معرفی کرده است.

هر تغییر زیر ناسازگار است و هرگز روی نسخهٔ موجود انجام نمی‌شود:

حذف یا تغییر نام فیلد، هدر یا نوع رویداد؛
تغییر نوع، قالب، واحد یا معنای یک فیلد؛
اجباری‌کردن فیلد اختیاری، یا تهی‌پذیرکردن فیلدی که تهی نبوده است؛
افزودن مقدار به فیلدی که فهرست بسته معرفی شده است.

تغییر ناسازگار فقط در قالب نسخهٔ طرح‌وارهٔ تازه‌ای که خودتان صریحاً انتخاب می‌کنید عرضه می‌شود. اشتراک‌های موجود هرگز خودبه‌خود به نسخهٔ تازه منتقل نمی‌شوند.

سیاست منسوخ‌سازی

منسوخ‌شدن هر مورد دست‌کم ۱۸۰ روز پیش از درخواست هرگونه مهاجرت، در گزارش تغییرات، در داشبورد و با ایمیل به مالکان حساب اعلام می‌شود.
اعلان، رویداد یا نسخه یا فیلد را دقیق نام می‌برد و جایگزین و راه مهاجرت را می‌گوید.
فیلد منسوخ در بدنه می‌ماند و رویداد منسوخ برای مشترکان فعلی در دسترس می‌ماند. منسوخ‌شدن به‌تنهایی هیچ چیزی را حذف نمی‌کند. حذف یک نسخه اعلان جداگانه‌ای لازم دارد، دست‌کم ۱۸۰ روز پس از اعلان منسوخ‌شدن.

استثناها

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 دارد ساخته می‌شوند. ویرایش، کلید هر نشانی بدون تغییر را نگه می‌دارد؛ نشانی تازه یا تغییرکرده کلید تازه می‌گیرد.
کلیدها را با POST /v1/marketing/automations/{id}/webhook-signing-secrets/regenerate عوض کنید؛ هر گیرنده کلید تازه می‌گیرد و همه برگردانده می‌شوند. کلیدهای قبلی همان لحظه از کار می‌افتند؛ پس اول هر گیرنده را طوری تنظیم کنید که هر دو را بپذیرد. نسخهٔ کپی‌شدهٔ اتوماسیون کلیدهای خودش را می‌گیرد، و اتوماسیونی که همهٔ گام‌های Webhook آن حذف شود کلیدهایش را از دست می‌دهد.
برای عوض‌کردن کلید فقط یک گیرنده، { "webhookUrl": "<نشانی گام>" } را در بدنهٔ درخواست regenerate بفرستید؛ گیرنده‌های دیگر کلیدشان را نگه می‌دارند. نشانی‌ای که نشانی یک گام Webhook همین اتوماسیون نباشد پاسخ 400 می‌گیرد.
اتوماسیونی که گیرنده‌هایش هنوز یک کلید مشترک دارند، هنگام فعال‌سازی یا ازسرگیری، یا پیش از فرستادن گام Webhook بعدی، به کلیدهای جدا برای هر گیرنده تقسیم می‌شود. هیچ درخواستی با کلیدی که گیرندهٔ دیگری هم دارد امضا نمی‌شود: اگر تقسیم ممکن نباشد، آن گام فرستاده نمی‌شود.
X-MLND-Event-Id برای یک‌بار اجرای یک گام برای یک مشترک ثابت است. آن را همراه با بازهٔ ۵ دقیقه‌ای t برای ردکردن درخواست‌های تکراری به کار ببرید.
اتوماسیونی که پیش از آمدن امضا ذخیره شده، تا وقتی دوباره ذخیره نشود یا کلیدش از نو ساخته نشود، درخواست بی‌امضا می‌فرستد.
این درخواست‌ها بهترین تلاش هستند: یک‌بار فرستاده می‌شوند و برنامهٔ تلاش دوباره ندارند. اتوماسیون، هر پاسخی که گیرنده بدهد، ادامه پیدا می‌کند.

نسخه‌بندی و سازگاری

نسخهٔ طرح‌وارهکپی پیوند بخش

شناسه‌هاکپی پیوند بخش

زمان‌هاکپی پیوند بخش

تعهد سازگاریکپی پیوند بخش

سیاست منسوخ‌سازیکپی پیوند بخش

استثناهاکپی پیوند بخش

گام‌های Webhook در اتوماسیون‌هاکپی پیوند بخش