Bilgi bankası

Webhook'lar

Sizi yoklama yapmaya zorlamak yerine posta geldiğinde uç noktanıza haber verir.

Ayrıntılar

Bugün Ayarlar → Webhook'lar bölümünden ve API üzerinden kullanılabilir: bir https uç noktası kaydedin, yirmi olaydan hangilerini istediğini seçin ve yalnızca oluşturulurken ve döndürülürken gösterilen, bir daha asla gösterilmeyen whsec_ imzalama gizli dizisini kopyalayın. Teslimatlar, herhangi bir API çağrısı tarafından değil posta kutusunun kendisi tarafından tetiklenen, gerçek ve imzalı POST istekleridir; dolayısıyla iletiyi ne göndermiş olursa olsun gelen postada, açılmalarda ve tıklamalarda tetiklenirler. Gönderim artık her yüzeyden tetikleniyor; eskiden yalnızca bazılarından tetikleniyordu: API, MCP, bir şablon ya da bir kural üzerinden yapılan gönderim email.sent olayını doğururken uygulamanın kendi ileti penceresinden gönderilen bir ileti bunu yapmıyordu, çünkü o pencere olayı yayan gönderim servisi üzerinden değil doğrudan posta kutusuna yazar. Olay artık hepsinin buluştuğu yer olan posta kutusunun kendisinde doğuruluyor; dolayısıyla uygulamada ileti yazmak, salı gününe zamanlamak ve API'ye istek atmak aynı webhook'u doğurmanın üç yoludur. Ertelenmiş bir gönderim bunu iki kez söyler: kabul edildiğinde email.scheduled ya da email.queued, gerçekten gittiğinde email.sent ve arada geri alırsanız email.cancelled. Posta kutusu başına on uç nokta; bu sınır yalnızca bu ekranda değil, bir uç noktanın kaydedildiği her yerde uygulanır.
Olaylar üç aileden gelir. On beşi tek bir iletiyle ilgilidir: email.received, email.replied, email.sent, email.delivered, email.failed, email.cancelled, email.scheduled, email.queued (scheduled'ın geri-alma kardeşi), email.delivery_delayed, email.bounced, email.complained, email.suppressed, email.opened, email.clicked ve email.downloaded. email.sent, gönderim servisinin iletiyi kabul ettiği; email.delivered, alıcı sunucunun kabul ettiği; email.delivery_delayed ise iletinin henüz ulaşmadığı ve hâlâ yeniden denendiği anlamına gelir. email.replied, gelen ileti posta kutusunda zaten bulunan bir iletiyi yanıtladığında email.received ile birlikte tetiklenir; böylece ikisini de isteyen bir tüketici ikisini de alır. email.downloaded, bir kişi indirme bağlantısı olarak giden bir dosyayı çektiğinde tetiklenir; tarayıcıları ve bağlantı önizleyicileri sayımın dışında tutan aynı sınıflandırıcı burada da işler ve hiçbir alıcı adı vermez, çünkü bağlantı iletinin gittiği herkes için aynıdır. Üçü bir alan adıyla ilgilidir: posta almaya başladığında domain.verified, gönderim kararı değiştiğinde domain.sending_changed ve siz istediğiniz için ya da yedi günlük toplayıcı doğrulanmamış olduğu için düşürdüğünde, kaldırıldığında domain.deleted. İkisi ise email.suppressed'den farklı bir şey olan bastırma listesinin kendisiyle ilgilidir: bir adres listeye girdiğinde suppression.added, bir adrese yeniden izin verildiğinde suppression.removed. Hiçbirine abone olmamak, email.replied dışındaki her ileti olayı anlamına gelir; bugün on dört tanedir, sonradan eklenen bir aileyi asla kapsamaz ve API bunu ["*"] olarak geri okur. Açık olmayı tercih ediyorsanız istediğiniz olayların adını verin. Her teslimat, zaman damgası, bir nokta ve ham gövde üzerinde HMAC-SHA-256 olan X-OpenEmail-Signature başlığını t=<unix>,v1=<hex> biçiminde, ayrıca X-OpenEmail-Event ve X-OpenEmail-Delivery başlıklarını taşır. Doğrulamayı baytlar geldiği haliyle yapın: ayrıştırıp yeniden serileştirmek anahtarların sırasını değiştirir ve imzayı bozar. 300 saniyelik yeniden oynatma penceresini uygulamak alıcının işidir ve SDK'nın doğrulayıcısı varsayılan olarak bunu kullanır.
https olmayan ya da herkese açık yönlendirilebilir olmayan her şey için kayıt reddedilir (loopback, RFC1918, link-local, CGNAT ve IPv6 karşılıkları) ve yönlendirmeler izlenmez; dolayısıyla bir 3xx başka bir yere kovalanmak yerine başarısız teslimat olarak kaydedilir. Alıcıya 5 saniye tanınır, uç noktalara teslimat paralel yapılır; böylece on uç nokta 50 saniye değil yine 5 saniye tutar ve son denemeler, yanıt kodu ve ne kadar sürdüğü ile birlikte o uç noktanın sayfasında listelenir.
Bir teslimat en fazla beş kez denenir. İlki olay gerçekleştiği anda gider; kendiliğinden düzelmesi makul olan bir başarısızlık 1 dakika, sonra 5, sonra 25 dakika, sonra 2 saat sonra yeniden denenir; bu da tek bir olayı yaklaşık iki buçuk saate yayar. Yeniden denemeler bellekte değil dayanıklı iş olarak tutulur; dolayısıyla bu pencerenin ortasındaki bir dağıtım onları kaybetmez. Yalnızca yinelemeye değer başarısızlıklar yinelenir: zaman aşımı, reddedilen bağlantı, 408, 425, 429 ya da herhangi bir 5xx. Başka herhangi bir 4xx, uç noktanın yükü bilerek reddetmesidir; dört kez daha sormak aynı yanıt için dört kat yük olurdu. Olay id'si bir kez üretilir ve her deneme onu X-OpenEmail-Delivery içinde taşır; böylece aynı id'yi iki kez gören bir alıcı, iki kez işlem yapmak yerine ikincisini düşürebilir. Arka arkaya 100 olay her denemede başarısız olduktan sonra uç nokta devre dışı bırakılır, çalışma alanına e-posta gönderilir ve neden uç noktanın kendisinde okunabilir olur. 410 Gone yanıtı veren bir uç nokta anında devre dışı bırakılır.
Arka arkaya 100 kez başarısız olan bir uç nokta sonsuza dek aranmak yerine kapatılır ve webhook erişimi olan herkese bunu bildiren bir e-posta gönderilir: hangisi olduğu, son denemenin ne rapor ettiği ve başarısız olduğu süre boyunca hiçbir şeyin kuyruğa alınmadığı. Sayım ARDIŞIKTIR ve teslim edilen herhangi bir deneme onu sıfırlar; dolayısıyla geçen mart ayındaki kötü bir öğleden sonra bugün devre dışı kalmış bir uç noktaya dönüşemez. Yeniden açmak sayımı da temizler. Konsol tek bir anahtar göstermek yerine iki durumu ayırır: sizin kapattığınız bir uç nokta, bizim kapattığımızdan farklı görünür.
Uç noktaları yönetmek, iki ayrı kapısı olan tek bir iştir. API üzerinden bu POST /webhooks, yama, silme, gizli diziyi döndürme, test ve teslimat günlüğüdür; SDK'da her biri için bir metot vardır. Uygulamada ise Ayarlar → Webhook'lar'dır ve ikinci bir kayıt defterine değil aynı kayıt defterine işler. Okuma webhooks:read ile korunur; böylece bir entegrasyon geliştiren herkes, sahip olmadan uç noktaları ve teslimat geçmişlerini (hangisinin tetiklendiğini, alıcının ne yanıtladığını, ne kadar sürdüğünü) görebilir. Kaydetmek, düzenlemek, test etmek, döndürmek ve silmek her iki yüzeyde de hem webhooks:write hem de posta kutusunun sahipliğini gerektirir; bu ikinci yarı bilinçlidir: bir uç noktanın adres ekseni yoktur, dolayısıyla çalışma alanının sahip olduğu her adresi konu ve alıcılarıyla birlikte alır ve izin yokluğu "bunların hepsi gönderilebilir" anlamına gelmez. Entegrasyon geliştiren ve postayı okumayan bir rol, bunu bunun yerine bir çalışma alanı anahtarıyla yürütür.