Python

Uç noktalar

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

Her yöntem

usage.py

from acme.secrets import store endpoint = client.webhooks.create({    'url': 'https://acme.com/hooks/mail',    'eventTypes': ['email.sent', 'email.bounced'],    'description': 'Billing service',}) store(endpoint['secret']) client.webhooks.list()client.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'][0]client.webhooks.get_delivery(endpoint['id'], latest['id'])client.webhooks.replay_delivery(endpoint['id'], latest['id'])rotated = client.webhooks.rotate_secret(endpoint['id'])store(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 yansıtmaz; bu yüzden başka bir şey yapmadan önce saklayın. Varsayılan küme için eventTypes'ı atlayın: email.replied dışındaki her email.* olayı. email.replied, domain.*, suppression.*, file.* ve form.* bir uç noktaya yalnızca uç nokta onları adlandırdığında ulaşır.

rotate_secret'in örtüşme penceresi yoktur. Eski gizli anahtar anında ç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ı.

Nelere abone olabilirsiniz

Listeyi işleyebilmeniz için WEBHOOK_EVENTS dışa aktarılır. Olaylar bu API'nin değil, **posta kutusunun** olaylarıdır: email.received uygulamaya gelen posta için, email.sent ise oluşturucunun gönderdiği bir ileti için tetiklenir. Abone olmak, kendi API trafiğinizi izlemekle aynı şey değildir.

file.uploaded, Dosyalar sayfasına bir dosya konduğunda, file.deleted ise bir dosya silindiğinde tetiklenir. Verileri FileEventData türündedir: fileId, filename, mimeType, sizeBytes, direction, to, threadId, messageId ve uploadedAt ya da deletedAt. to, dosyanın ait olduğu adrestir; çalışma alanının tamamına ait bir dosya için null olur.

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

form.submitted, biri formlarınızdan biri üzerinden kaydolduğunda tetiklenir; form.confirmed ise kişi onay bağlantısını açtığı ya da siz kaydı onayladığınız için bekleyen bir kayıt kitlelere katıldığında tetiklenir. form.submitted, FormSubmittedEventData taşır: formId, formName, submissionId, email, status, answers, audienceIds, sourceUrl ve submittedAt. form.confirmed, FormConfirmedEventData taşır: formId, formName, submissionId, email, audienceIds, değeri link ya da approval olan via ve confirmedAt.

Ç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.

Bu veri biçimlerinin her biri openemail.types içinde bir TypedDict'tir. Örneğin doğrulanmış bir olayı WebhookPayload[FileEventData] olarak işaretleyin; bir tür denetleyicisi event['data'] içinde ne olduğunu bilir.

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

webhook_test.py

result = client.webhooks.test('whe_…')delivery = result['delivery'] if delivery is not None:    print(delivery['status'], delivery['responseCode']) for d in client.webhooks.iterate_deliveries('whe_…'):    print(d['eventType'], d['status'], d['responseCode'], d['error'])

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

Yeniden göndermek

webhook_replay.py

detail = client.webhooks.get_delivery('whe_…', 'whd_…')print(detail['payload'], detail['responseBody'], detail['replayRefusal']) replay = client.webhooks.replay_delivery('whe_…', 'whd_…')print(replay['delivery']['status'], replay['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 bir olayı hemen gönderir ve sunucunuzun verdiği yanıtı 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 takvimlerine göre sürerler.
O anda aynı olayın otomatik bir yeniden denemesi gönderiliyorsa replay_delivery hiçbir şey göndermez ve 409 retry_in_progress ile reddedilir; olayın başka bir yeniden oynatması hâlâ gönderiliyorsa 409 replay_in_progress ile reddedilir; böylece alıcınız, aynı anda gönderilen iki yeniden oynatmadan bile aynı anda iki kopya almaz. Birkaç saniye bekleyip get_delivery ile okuyun, çünkü o yeniden deneme ya da yeniden oynatma olayı teslim edebilir. Yeniden oynatma tek seferde tek olay içindir: başarısız tüm teslimatları yeniden gönderen bir çağrı yoktur.
Ayrıca kapalı bir uç noktayı (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 denemeyi (delivery_not_replayable) 409 ile reddeder. get_delivery bu yanıtı önceden replayRefusal olarak bildirir.

SDK, replay_delivery çağrısını kendiliğinden asla yeniden denemez, çünkü kaybolan bir yanıttan sonraki yeniden deneme olayı bir kez daha gönderir.

Her ret, status değeri 409, is_conflict değeri true ve nedeni code olarak taşıyan bir OpenEmailApiError fırlatır; bu neden WEBHOOK_REPLAY_ERROR_CODES içindeki değerlerden biridir.

Parametreler: webhooks.create

urlstrzorunlu: Teslimatların POST edildiği yer. Yalnızca HTTPS ve host, `localhost`, bir `.localhost`/`.local`/`.internal` adı ya da bir loopback, özel, CGNAT veya link-local IP değeri olamaz. Bu, sizin verdiğiniz bir adrese yapılan sunucu tarafı bir isteklir; bu yüzden bunlar `url` üzerinde 422 olur. Denetim, host adını yazıldığı gibi okur ve asla DNS çözümlemesi yapmaz. Saklanan şey, gönderdiğinizin URL ayrıştırıcısı tarafından yeniden seri hâle getirilmiş biçimidir; bu yüzden `https://acme.com` geri okunduğunda `https://acme.com/` olur.
eventTypeslist[WebhookEvent]: Bu uç noktaya hangi olayların ulaşacağı: `WEBHOOK_EVENTS` içindeki adlardan herhangi biri. `POST /webhooks` diziyi var olan olay sayısıyla sınırlar; bundan bir fazlası `eventTypes` üzerinde 422 olur, `PATCH` ise sınırlamaz. Yalnızca uzunluk sınırlanır; yinelenen bir ad gönderdiğiniz gibi saklanır ve geri okunur. Atlanan ya da boş bırakılan değer boş bir liste olarak saklanır; `['*']` olarak geri okunmasının nedeni budur ve bu, `email.replied` dışındaki her `email.*` olayı anlamına gelir, bugün için on dört tane, ve asla domain, suppression ya da file ailelerini kapsamaz. Sonradan eklenen bir aile, onu adlandırmamış bir uç noktaya asla ulaşmaz; böylece bir entegrasyon, bir sürüm yüzünden daha önce hiç görmediği bir biçimi almaya başlayamaz.
descriptionstr: Uç nokta için bir etiket, en fazla 200 karakter; böylece bir webhook listesi bir URL sütunu yerine adlar olarak okunur. Atlandığında null olarak saklanır ve döndürülür.

Yanıt: CreatedWebhookResource

objectLiteral['webhook']: Her zaman `'webhook'`; düz bir okumanın döndürdüğü ayırıcının aynısı, çünkü gizli anahtar kendine ait bir nesne türü değil, olağan biçimin üzerindeki fazladan bir anahtardır. `secret` alanının bulunup bulunmadığına bu alan değil, çağırdığınız yöntem karar verir.
idstr: 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`.
urlstr: HTTPS ve engellenen host denetimlerinden geçmiş hâliyle, saklanan uç nokta. Ayrıştırılmış URL'nin yeniden seri hâle getirilmiş biçimidir; bu yüzden gönderdiğiniz stringle değil, bu değerle karşılaştırın.
descriptionstr | None: Ona verdiğiniz etiket ya da hiç vermediyseniz null. Açıkça null gönderen bir `update`, değeri yeniden null'a temizler.
eventTypeslist[WebhookEvent] | ['*']: Abone olunan olaylar ya da uç nokta hiçbirini adlandırmadıysa `['*']`. `['*']`, saklanan boş bir listenin okumada gösterilme biçimidir, geri gönderilemez ve tüm katalog yerine on dört ileti olayını temsil eder. `create` ve `update` yalnızca birebir olay adlarını kabul eder.
enabledbool: Teslimatların denenip denenmediği; devre dışı bir uç nokta, olaylar sevk edilirken atlanır ve gizli anahtarı ile teslimat geçmişini korur. Burada her zaman true'dur, çünkü `WebhookCreate`'te `enabled` yoktur, yalnızca `WebhookPatch`'te vardır.
lastDeliveryAtstr | None: 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 damgalanır; yani size uç noktanın denendiğini söyler, nasıl gittiğini ise `list_deliveries` söyler. İlk denemeye kadar null'dur ve bu yüzden `create`'te her zaman null olur.
createdAtstr: 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.
secretstr: Her teslimatın `X-OpenEmail-Signature` değerini imzalayan HMAC-SHA-256 anahtarı: `whsec_` ve ardından base64url biçiminde 32 rastgele bayt; `verify_webhook_signature`'a verdiğiniz şey de budur. Yalnızca `create` ve `rotate_secret` tarafından döndürülür, başka hiçbir şey tarafından değil. Bir okuma onu asla yansıtmaz; bu yüzden şimdi saklayın. Kaybolan bir gizli anahtar yalnızca `rotate_secret` ile değiştirilebilir ve bu da eskisini anında geçersiz kılar.

Günlükleri süzmek

webhook_logs.py

from datetime import datetime, timedelta, timezone failed = client.webhooks.list_workspace_deliveries(    status='failed',    since=datetime.now(timezone.utc) - timedelta(days=1),)print(len(failed['items'])) history = client.webhooks.list_activity('whe_…')print([(change['type'], change['actor']['label'] if change['actor'] else None) for change in history['items']])

list_deliveries tek bir uç noktayı, list_workspace_deliveries ise her uç noktayı ya da endpoint_ids= içinde adı geçenleri okur ve ikisi de konsolun Teslimler sekmesinin filtreleri olan status=, since= ve until= değerlerini alır. list_activity ve list_workspace_activity denetim günlüğünü okur: kimin neyi oluşturduğu, değiştirdiği, kapatıp açtığı, döndürdüğü, test ettiği, yeniden gönderdiği veya kaldırdığı. Her birinin yanında bir list_all_… ve bir iterate_… vardır ve çalışma alanı günlüğünün her satırı endpointId taşır.

since= ve until= bir datetime ya da ISO 8601 dizesi alır. Saat dilimi bilgisi olmayan (naive) bir datetime yerel saat olarak okunur ve UTC'ye dönüştürülür; bu yüzden yukarıdaki gibi saat dilimi bilgisi olan (aware) bir değer geçirin.

Uç noktalar

Her yöntem

Nelere abone olabilirsiniz

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

Yeniden göndermek

Parametreler: webhooks.create

Yanıt: CreatedWebhookResource

Günlükleri süzmek

Referans

Gelen kutunuz,
kendi kurallarınızla.

Uç noktalar

Her yöntem

Nelere abone olabilirsiniz

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

Yeniden göndermek

Parametreler: webhooks.create

Yanıt: CreatedWebhookResource

Günlükleri süzmek

Referans

Gelen kutunuz,kendi kurallarınızla.

Gelen kutunuz,
kendi kurallarınızla.