Sürümleme ve Uyumluluk

MailLand webhook yüklerini yalnızca mevcut bir alıcının yok sayabileceği biçimde değiştirir. Bu sayfa bu taahhüdü, bir alıcının güvenebileceği kimlikleri ve zaman damgalarını, uyumsuz bir değişiklik gündeme gelmeden önce neler olacağını açıklar.

Şema sürümüBölüm bağlantısını kopyala

Her olay türünün yükü için bir şema sürümü vardır; pozitif bir tam sayıdır. Bugün tüm olaylar 1 sürümündedir.

• Gövde bunu schema_version alanında taşır.
• X-MLND-Event-Version başlığı aynı değeri taşır.
• schema_version içermeyen bir gövde (alan eklenmeden önce gönderilmiş) 1 sürümündedir.

Sürüm olay oluşturulurken sabitlenir; bu yüzden aynı olayın her yeniden denemesi aynı sürümü taşır. X-MLND-Signature içindeki v1 ise imza düzeninin sürümüdür ve bundan bağımsızdır.

KimliklerBölüm bağlantısını kopyala

Tekilleştirmeyi event_id ile yapın, asla teslimat kimliğiyle yapmayın. Olaylar birden fazla kez ve sırasız gelebilir; ileti olaylarını bir ileti için yalnızca artan data.status_version değerine göre sıralayın.

Zaman damgalarıBölüm bağlantısını kopyala

Gövdedeki tüm zamanlar UTC'dir ve sonunda Z bulunan ISO 8601 biçimindedir. Gövde her denemede aynıdır; yalnızca denemenin başlıkları değişir. İmza t değerini ve ham gövdeyi kapsar, diğer başlıkları kapsamaz; onları yönlendirme üst verisi olarak görün ve gövdeye güvenin.

Uyumluluk taahhüdüBölüm bağlantısını kopyala

Alıcılar tanımadıkları JSON alanlarını ve HTTP başlıklarını yok saymalıdır. Bu kuralla aşağıdaki her değişiklik güvenlidir ve yeni bir şema sürümü olmadan yapılır:

• gövdeye ya da data nesnesine alan veya yeni bir başlık eklemek;
• yalnızca abone olduktan sonra alacağınız yeni bir olay türü eklemek;
• bu belgelerin açık uçlu olarak tanımladığı bir alana yeni değer eklemek.

Aşağıdakilerin her biri uyumsuz değişikliktir ve mevcut bir sürüme asla uygulanmaz:

• bir alanı, başlığı veya olay türünü kaldırmak ya da yeniden adlandırmak;
• bir alanın türünü, biçimini, birimini veya anlamını değiştirmek;
• isteğe bağlı bir alanı zorunlu, null olmayan bir alanı null olabilir yapmak;
• kapalı liste olarak belgelenmiş bir alana yeni değer eklemek.

Uyumsuz bir değişiklik yalnızca sizin açıkça seçtiğiniz yeni bir şema sürümü olarak yayımlanır. Mevcut abonelikler hiçbir zaman kendiliğinden yeni sürüme geçirilmez.

Kullanımdan kaldırma politikasıBölüm bağlantısını kopyala

• Bir kullanımdan kaldırma, herhangi bir geçiş istenmeden en az 180 gün önce değişiklik günlüğünde, panelde ve hesap sahiplerine e-postayla duyurulur.
• Duyuru ilgili olayı, sürümü veya alanı, yerine geçeni ve geçiş yolunu tam olarak belirtir.
• Kullanımdan kaldırılan bir alan yükte kalır; kullanımdan kaldırılan bir olay mevcut abonelere açık kalır. Kullanımdan kaldırma tek başına hiçbir şeyi silmez. Bir sürümün kaldırılması, kullanımdan kaldırma duyurusundan en az 180 gün sonra yapılacak ayrı bir duyuru gerektirir.

İstisnalarBölüm bağlantısını kopyala

Otomasyon Webhook adımlarıBölüm bağlantısını kopyala

Bir otomasyonun Webhook adımları müşteri webhook'larıyla tamamen aynı biçimde imzalanır: X-MLND-Signature başlığını o adımın alıcısına ait imza gizli anahtarıyla, aynı adımları izleyerek doğrulayın.

• Her alıcının (farklı bir adım URL'si) kendi gizli anahtarı vardır; bu yüzden hiçbir alıcı başka bir alıcının kabul edeceği imzalar üretemez. Aynı URL'ye gönderen adımlar tek bir alıcıdır ve onun anahtarını paylaşır.
• Gizli anahtarları GET /v1/marketing/automations/{id}/webhook-signing-secrets ile okuyun: adım sırasına göre { webhookUrl, secret } öğelerinden oluşan bir secrets listesi. Webhook adımı olan bir otomasyon oluşturulduğunda veya kaydedildiğinde oluşurlar. Bir düzenleme, değişmeyen her URL'nin anahtarını korur; yeni veya değişen bir URL yeni bir anahtar alır.
• POST /v1/marketing/automations/{id}/webhook-signing-secrets/regenerate ile değiştirin; her alıcı yeni bir anahtar alır ve hepsi döndürülür. Eski anahtarlar hemen geçersiz olur; bu yüzden önce her alıcının ikisini de kabul etmesini sağlayın. Bir otomasyonun kopyası kendi anahtarlarını alır; tüm Webhook adımları kaldırılan bir otomasyon ise anahtarlarını kaybeder.
• Yalnızca bir alıcıyı döndürmek için regenerate isteğinin gövdesinde { "webhookUrl": "<adım URL'si>" } gönderin; diğer tüm alıcılar anahtarlarını korur. Otomasyonun Webhook adım URL'si olmayan bir URL 400 döner.
• Alıcıları hâlâ tek bir anahtarı paylaşan bir otomasyon, etkinleştirildiğinde veya sürdürüldüğünde ya da bir sonraki Webhook adımı gönderilmeden önce alıcı başına anahtarlara ayrılır. Bir istek asla başka bir alıcının sahip olduğu bir anahtarla imzalanmaz: ayırma yapılamazsa adım gönderilmez.
• X-MLND-Event-Id, bir abone için bir adımın bir çalıştırmasında sabittir. Tekrar saldırılarını reddetmek için bunu t üzerindeki 5 dakikalık pencereyle birlikte kullanın.
• İmzalama özelliği gelmeden önce kaydedilmiş bir otomasyon, yeniden kaydedilene ya da anahtarı yeniden üretilene kadar imzasız istek gönderir.
• Bu istekler en iyi çaba esaslıdır: tek deneme yapılır, yeniden deneme takvimi yoktur. Otomasyon, alıcının yanıtı ne olursa olsun devam eder.