Ruby

Uç noktalar

`webhooks.list`, `list_all`, `iterate`, `get`, `create`, `update`, `delete`, `rotate_secret`, `test`, `get_delivery` ve `replay_delivery`, ayrıca teslimat ve etkinlik günlükleri.

Her yöntem

webhooks.rb

endpoint = client.webhooks.create(  url: "https://acme.com/hooks/mail",  eventTypes: ["email.sent", "email.bounced"],  description: "Billing service") File.write(".openemail-webhook-secret", endpoint[:secret]) client.webhooks.listclient.webhooks.get(endpoint[:id])client.webhooks.update(endpoint[:id], enabled: false)client.webhooks.test(endpoint[:id])latest = client.webhooks.list_deliveries(endpoint[:id], limit: 1).items.firstclient.webhooks.get_delivery(endpoint[:id], latest[:id])client.webhooks.replay_delivery(endpoint[:id], latest[:id])rotated = client.webhooks.rotate_secret(endpoint[:id])File.write(".openemail-webhook-secret", rotated[:secret])client.webhooks.delete(endpoint[:id])

rotate_secret dışında gizli anahtarın döndürüldüğü TEK an create'tir. Bir okuma onu asla geri döndürmez; bu yüzden başka bir şey yapmadan önce onu saklayın. Varsayılan küme için eventTypes değerini belirtmeyin: email.replied dışındaki her email.* olayı. email.replied, domain.*, suppression.*, file.* ve form.* bir uç noktaya ancak uç nokta onları belirttiğinde ulaşır.

rotate_secret için bir çakışma penceresi yoktur. Eski gizli anahtar hemen çalışmayı bırakır; bu yüzden döndürmeden önce yenisini dağıtın. Asla otomatik olarak yeniden denenmez: bir yeniden deneme ikinci kez döndürür ve ilk denemenin döndürdüğü gizli anahtarı geçersiz kılardı.

create da yeniden denenmez; bu yüzden bir ağ hatası, hiç görmediğiniz bir gizli anahtarla oluşturulmuş bir uç nokta bırakabilir. Onu yeniden oluşturmadan önce list ile denetleyin. Bir çalışma alanı varsayılan olarak 10 uç nokta tutar ve sınırı aşan bir sonraki 422 workspace_limit_reached verir.

Nelere abone olabilirsiniz

OpenEmail::WEBHOOK_EVENTS her olay adından oluşan dondurulmuş bir Hash'tir; böylece listeyi bir istek yapmadan görüntüleyebilirsiniz. webhooks.list_events ise aynı adları her biri için bir cümleyle ve bir uç noktanın tabi olduğu sınırlarla birlikte döndürür. Olaylar bu API'nin değil, **posta kutusunun** olaylarıdır: email.received uygulamaya gelen posta için, email.sent ise yazma ekranının gönderdiği bir ileti için tetiklenir. Abone olmak, kendi API trafiğinizi izlemekle aynı şey değildir.

file.uploaded bir dosya Dosyalar sayfasına konduğunda, file.deleted ise bir dosya silindiğinde tetiklenir. data alanları fileId, filename, mimeType, sizeBytes, direction, to, threadId, messageId ve uploadedAt ya da deletedAt içerir. to dosyanın ait olduğu adrestir; tüm çalışma alanına ait bir dosya için nil'dir.

Dosya olayları varsayılan kümede değildir; bu yüzden bir uç nokta onları yalnızca eventTypes içinde belirttiğinde alır. Bazı adreslerle sınırlı bir uç nokta yalnızca o adreslerin dosyalarından haberdar olur; bu yüzden tüm çalışma alanı için yapılan, to değeri nil olan bir yükleme ona gönderilmez.

form.submitted, biri formlarınızdan biri aracılığıyla kaydolduğunda; form.confirmed ise bekleyen bir kayıt, kişi onay bağlantısını açtığı ya da siz onu onayladığınız için kitlelere katıldığında tetiklenir. form.submitted olayının data alanı formId, formName, submissionId, email, status, answers, audienceIds, sourceUrl ve submittedAt içerir. form.confirmed olayının data alanı formId, formName, submissionId, email, audienceIds, değeri link ya da approval olan via ve confirmedAt içerir.

Çift onayı olmayan bir formdaki kayıt, status değeri added olan bir form.submitted gönderir ve form.confirmed göndermez; bu yüzden bu ikiliyi birinin katıldığı an olarak ele alın. Onaylamadan önce yeniden kaydolan kişi aynı submissionId değerini korur ve form.submitted yalnızca yanıtları değiştiyse yeniden gönderilir. Form olayları varsayılan kümede değildir ve bazı adreslerle sınırlı bir uç nokta bunları asla almaz, çünkü kayıtlar tüm çalışma alanına aittir.

Çalıştığını kanıtlamak

webhook_test.rb

result = client.webhooks.test("whe_3f9c2a7b1e4d8f60a5c7b92d")puts result.dig(:delivery, :status), result.dig(:delivery, :responseCode) client.webhooks.iterate_deliveries("whe_3f9c2a7b1e4d8f60a5c7b92d") do |delivery|  puts "#{delivery[:eventType]} #{delivery[:status]} #{delivery[:responseCode]} #{delivery[:error]}"end

test imzalı, yapay bir email.sent olayı gönderir ve denemenin bitmesini bekler. Alıcınız ne yanıt verirse versin normal şekilde döner; bu yüzden dallanmayı çağrının hata fırlatıp fırlatmadığına göre değil, delivery[:status] değerine göre yapın. Bir 4xx yararlı bir yanıttır: URL'ye ulaşılabiliyordur ve ret sizin kendi işleyicinizden, çoğu zaman onun imza denetiminden gelmiştir.

nil bir responseCode hiç yanıt olmadığı anlamına gelir (DNS, TLS, bir zaman aşımı); bu, 0 diyen bir yanıttan farklı bir olgudur. Her satır attempt ve maxAttempts taşır; bu yüzden birkaç satır tek bir olayı tanımlayabilir: satırlar arasındaki aynı eventId olayı, deneme numarası ise denemeyi gösterir. nextAttemptAt bir satırdan sonraki otomatik yeniden denemenin ne zaman yapılacağını söyler.

Yeniden göndermek

webhook_replay.rb

detail = client.webhooks.get_delivery("whe_3f9c2a7b1e4d8f60a5c7b92d", "whd_8c1e4a7f2b9d3e6a0c5f1b28")p detail[:payload], detail[:responseBody], detail[:replayRefusal] replay = client.webhooks.replay_delivery("whe_3f9c2a7b1e4d8f60a5c7b92d", "whd_8c1e4a7f2b9d3e6a0c5f1b28")p replay.dig(:delivery, :status), replay.dig(:delivery, :responseCode)

Başarısız olmaya devam eden bir teslimat en fazla 8 kez denenir: anında, ardından 1 dakika, 5 dakika, 30 dakika, 2 saat, 5 saat, 10 saat ve 10 saat sonra; toplamda yaklaşık 27 buçuk saat. Yalnızca yinelemeye değer bir başarısızlık yinelenir: yanıt yok, 408, 425, 429 ya da bir 5xx. Yeniden oynatma, saklanan olayı aynı id, type, createdAt ve data ile yeniden gönderir; böylece daha önce işlediği id'leri düşüren bir alıcı onu zaten bildiği olay olarak ele alır. Yalnızca imza yenidir.

replay_delivery tek bir olayı hemen gönderir ve sunucunuzun yanıtını döndürür. Teslim edilmiş bir denemede de çalışır ve asla yeniden denenmez. Göndermeden önce o olayın henüz başlamamış otomatik yeniden denemeleri duraklatılır: yeniden oynatma teslim edilirse iptal edilmiş olarak kalırlar, başarısız olursa kendi zamanlamalarıyla devam ederler.
O anda aynı olayın otomatik bir yeniden denemesi gönderiliyorsa replay_delivery hiçbir şey göndermez ve 409 retry_in_progress fırlatır; olayın başka bir yeniden oynatması hâlâ gönderiliyorsa 409 replay_in_progress fırlatır. Böylece alıcınız, aynı anda gönderilen iki yeniden oynatmadan bile, asla aynı anda iki kopya almaz. Birkaç saniye bekleyin ve get_delivery okuyun, çünkü o yeniden deneme ya da yeniden oynatma olayı teslim edebilir. Yeniden oynatma her seferinde tek bir olay içindir: başarısız her teslimatı yeniden gönderen bir çağrı yoktur.
Ayrıca kapatılmış bir uç nokta (webhook_disabled), uç noktanın artık dinlemediği (event_not_subscribed) ya da artık kapsamadığı (event_out_of_scope) bir olay ve saklanmış olayı olmayan bir deneme (delivery_not_replayable) için de 409 fırlatır. get_delivery bu yanıtı önceden replayRefusal olarak bildirir.

Gem replay_delivery çağrısını asla kendiliğinden yeniden denemez, çünkü kaybolan bir yanıttan sonraki yeniden deneme olayı tekrar gönderirdi.

Parametreler: webhooks.create

urlStringzorunlu: Teslimatların POST ile gönderildiği yer. Yalnızca HTTPS; konak `localhost`, bir `.localhost`, `.local` ya da `.internal` adı veya geri döngü (loopback), özel, CGNAT ya da link-local bir IP değeri olamaz. Bu, sağladığınız bir adrese yapılan sunucu taraflı bir istektir; bu yüzden bunlar `url` üzerinde 422 `invalid_webhook_url` verir. Denetim ana bilgisayar adını yazıldığı gibi okur ve her teslimat konağı yeniden çözümleyip bu aralıklardan birindeki bir adrese göndermeyi reddeder. Teslimatlar asla yönlendirmeleri izlemez; bu yüzden son adresi kaydedin. Saklanan, gönderdiğinizin URL ayrıştırıcısı tarafından yeniden serileştirilmiş hâlidir; bu yüzden `https://acme.com` geri `https://acme.com/` olarak okunur.
eventTypesArray<String>: Bu uç noktaya hangi olayların ulaştığı: `OpenEmail::WEBHOOK_EVENTS` içindeki değerlerden herhangi biri. `create`, Array'i var olan olay sayısıyla sınırlar; bu yüzden bundan bir fazlası `eventTypes` üzerinde 422 verir, `update` ise sınırlamaz. Yalnızca uzunluk sınırlanır; tekrarlanan bir ad gönderdiğiniz gibi saklanır ve geri okunur. Belirtilmez ya da boş verilirse boş bir liste olarak saklanır; bu yüzden geri `["*"]` olarak okunur ve `email.replied` dışındaki her `email.*` olayı (bugün on dört tane) anlamına gelir, alan adı, engelleme, dosya ya da form ailelerini asla içermez. Sonradan eklenen bir aile onu belirtmemiş bir uç noktaya asla ulaşmaz; böylece bir entegrasyon bir sürüm yüzünden hiç görmediği bir biçimi almaya başlayamaz.
descriptionString: Uç nokta için bir etiket, en fazla 200 karakter; böylece bir webhook listesi bir URL sütunu olarak değil, adlar olarak okunur. Belirtilmezse nil olarak saklanır ve döndürülür.
addressAllowlistArray<String>: Bu uç noktanın haberdar olduğu tekil adresler. Bir olay, ilgili olduğu adres bu listede olduğunda ya da alan adı `domainAllowlist` içinde olduğunda teslim edilir. İkisini de boş bırakırsanız uç nokta çalışma alanının sahip olduğu her adresten haberdar olur. En fazla 50; bu çalışma alanının sahip olmadığı bir adres 422 `invalid_parameter` verir.
domainAllowlistArray<String>: Bu uç noktanın haberdar olduğu, sonradan eklenen adresler dahil, alan adlarının tamamı. Bir alan adı kendi `domain.*` olaylarını da taşır. En fazla 25.
api_keyString: Uç noktayı istemcinin anahtarı yerine bu anahtarla oluşturur.

Yanıt: oluşturulan uç nokta

Symbol anahtarlı bir Hash. get, list ve update aynı biçimi secret olmadan döndürür.

objectString: Her zaman `webhook`; sıradan bir okumanın döndürdüğü aynı ayırıcı, çünkü gizli anahtar kendine ait bir nesne türü değil, sıradan biçimdeki fazladan bir anahtardır. `secret` alanının bulunup bulunmayacağına bu alan değil, çağırdığınız metot karar verir.
idString: Uç noktanın tanımlayıcısı: `whe_` ve ardından 24 onaltılık karakter. Diğer her webhook çağrısı bunu alır: `get`, `update`, `delete`, `rotate_secret`, `test`, `list_deliveries`, `list_all_deliveries`, `iterate_deliveries`, `get_delivery` ve `replay_delivery`.
urlString: HTTPS ve engellenmiş konak denetimlerinden geçmiş, saklandığı hâliyle uç nokta. Ayrıştırılıp yeniden serileştirilmiş URL'dir; bu yüzden gönderdiğiniz String ile değil, bu değerle karşılaştırın.
descriptionString or nil: Verdiğiniz etiket; vermediyseniz nil. `description: nil` gönderen bir `update` onu temizler.
eventTypesArray<String>: Abone olunan olaylar; uç nokta hiçbirini belirtmediyse `["*"]`. `["*"]`, saklanan boş bir listenin okumada gösterildiği biçimdir ve geri gönderilemez; kataloğun tamamını değil, on dört ileti olayını temsil eder. `create` ve `update` yalnızca olayların harfi harfine adlarını kabul eder.
enabledBoolean: Teslimatların denenip denenmeyeceği. Devre dışı bir uç nokta, olaylar dağıtılırken atlanır ve gizli anahtarını ve teslimat geçmişini korur. Burada her zaman true'dur, çünkü `enabled` değerini yalnızca `update` alır.
disabledAtString or nil: Sunucunun art arda 100 başarısız teslimattan sonra uç noktayı kapattığı an. Açık olduğu sürece ve onu kendiniz kapattığınızda nil.
disabledReasonString or nil: Sunucunun onu neden kapattığı. `disabledAt` nil olduğunda her zaman nil.
consecutiveFailuresInteger: Art arda başarısız teslimat sayısı. Teslim edilen herhangi bir olay onu 0'a sıfırlar; `enabled: true` ile yapılan bir `update` de öyle.
addressAllowlistArray<String>: Bu uç noktanın haberdar olduğu tekil adresler.
domainAllowlistArray<String>: Bu uç noktanın haberdar olduğu alan adlarının tamamı. İki listenin de boş olması, çalışma alanının sahip olduğu her adres anlamına gelir.
lastDeliveryAtString or nil: Son başarının değil, son teslimat DENEMESİNİN ISO 8601 zaman damgası. Başarısız bir POST'tan sonra da yazılır; bu yüzden uç noktanın denendiğini söyler, nasıl sonuçlandığını ise `list_deliveries` söyler. İlk denemeye kadar nil'dir, bu yüzden `create` üzerinde her zaman nil'dir.
createdAtString: Uç noktanın kaydedildiği anın ISO 8601 zaman damgası. `list`, uç noktaları bu alana göre en yeniden başlayarak döndürür.
secretString: Her teslimatın `X-OpenEmail-Signature` başlığını imzalayan HMAC-SHA-256 anahtarı: `whsec_` ve ardından 43 base64url karakteri; `OpenEmail.verify_webhook_signature` metoduna önekiyle birlikte geçirdiğiniz değer budur. Yalnızca `create` ve `rotate_secret` tarafından döndürülür. Bir okuma onu asla geri döndürmez; bu yüzden şimdi saklayın. Kaybolan bir gizli anahtar yalnızca, eskisini hemen geçersiz kılan `rotate_secret` ile değiştirilebilir.

Günlükleri süzmek

webhook_logs.rb

failed = client.webhooks.list_workspace_deliveries(status: "failed", since: Time.now - 86_400)p failed.items.map { |delivery| [delivery[:endpointId], delivery[:eventType], delivery[:responseCode]] } history = client.webhooks.list_activity("whe_3f9c2a7b1e4d8f60a5c7b92d")p history.items.map { |change| [change[:type], change.dig(:actor, :label)] }

list_deliveries tek bir uç noktayı, list_workspace_deliveries ise her uç noktayı ya da endpoint_ids: içinde belirtilenleri okur; ikisi de konsolun Teslimatlar sekmesindeki filtreler olan status:, since: ve until: alır. list_activity ve list_workspace_activity denetim günlüğünü okur: kimin neyi oluşturduğu, değiştirdiği, açıp kapattığı, döndürdüğü, test ettiği, yeniden oynattığı ya da kaldırdığı. Her birinin yanında bir list_all_ ve bir iterate_ sürümü vardır ve çalışma alanı günlüğünün her satırı endpointId taşır. webhooks.stats, seçtiğiniz bir pencere için Analiz sekmesinin arkasındaki sayıları döndürür.

since: ve until: bir Time, bir DateTime ya da String olarak bir ISO 8601 anı alır; bir Ruby Date ise o günün UTC gece yarısı anlamına gelir. until bir Ruby anahtar sözcüğüdür, ancak diğerleri gibi bir anahtar kelime argümanı olarak çalışır: list_deliveries(id, since: start, until: finish).