PHP

Uç noktalar

`webhooks->list`, `listAll`, `iterate`, `get`, `create`, `update`, `delete`, `rotateSecret`, `test`, `getDelivery` ve `replayDelivery`, ayrıca teslimat ve etkinlik günlükleri.

Her yöntem

webhooks.php

use OpenEmail\Constants\WebhookEvents; $endpoint = $client->webhooks->create([    'url' => 'https://acme.com/hooks/mail',    'eventTypes' => [WebhookEvents::EMAIL_SENT, WebhookEvents::EMAIL_BOUNCED],    'description' => 'Billing service',]); file_put_contents('.openemail-webhook-secret', $endpoint['secret']); $client->webhooks->list();$client->webhooks->get($endpoint['id']);$client->webhooks->update($endpoint['id'], ['enabled' => false]);$client->webhooks->test($endpoint['id']); foreach ($client->webhooks->listDeliveries($endpoint['id'], limit: 1) as $latest) {    $client->webhooks->getDelivery($endpoint['id'], $latest['id']);    $client->webhooks->replayDelivery($endpoint['id'], $latest['id']);} $rotated = $client->webhooks->rotateSecret($endpoint['id']);file_put_contents('.openemail-webhook-secret', $rotated['secret']); $client->webhooks->delete($endpoint['id']);

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

list bir OpenEmail\Result\Page döndürür, listAll tüm uç noktaları tek bir dizi içinde döndürür, iterate ise uç noktaları birer birer veren bir Generator döndürür. create ve update gövdeyi API'deki adlarıyla tek bir dizi olarak alır ve her uç nokta camelCase anahtarlı bir dizi olarak döner.

rotateSecret'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ı.

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\Constants\WebhookEvents her olayı bir sabit olarak adlandırır ve WebhookEvents::values() bunları listeler; böylece listeyi bir istek yapmadan görüntüleyebilirsiniz. webhooks->listEvents ise aynı adları her biri için bir etiketle ve bir uç noktanın tabi olduğu, maxEndpoints, maxAddresses ve maxDomains içindeki 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 null'dır.

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

$result = $client->webhooks->test('whe_3f9c2a7b1e4d8f60a5c7b92d');echo $result['delivery']['status'], ' ', $result['delivery']['responseCode'] ?? 'no response', PHP_EOL; foreach ($client->webhooks->iterateDeliveries('whe_3f9c2a7b1e4d8f60a5c7b92d') as $delivery) {    echo $delivery['eventType'], ' ', $delivery['status'], ' ', $delivery['responseCode'] ?? '-', ' ', $delivery['error'] ?? '', PHP_EOL;}

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 istisna fırlatıp fırlatmadığına göre değil, $result['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.

Değeri null olan 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.php

$detail = $client->webhooks->getDelivery('whe_3f9c2a7b1e4d8f60a5c7b92d', 'whd_8c1e4a7f2b9d3e6a0c5f1b28');echo json_encode($detail['payload'], JSON_THROW_ON_ERROR), PHP_EOL;echo $detail['responseBody'] ?? 'no answer', ' ', $detail['replayRefusal']['code'] ?? 'replayable', PHP_EOL; $replay = $client->webhooks->replayDelivery('whe_3f9c2a7b1e4d8f60a5c7b92d', 'whd_8c1e4a7f2b9d3e6a0c5f1b28');echo $replay['delivery']['status'], ' ', $replay['delivery']['responseCode'] ?? 'no response', PHP_EOL;

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.

replayDelivery 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 replayDelivery 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 getDelivery 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. Her biri bir ConflictException'dır ve OpenEmail\Constants\WebhookReplayErrorCodes kodları adlandırır. getDelivery bu yanıtı önceden replayRefusal olarak bildirir: yeniden oynatma gerçekleşecekse null, aksi hâlde code ve message içeren bir dizi.

Paket replayDelivery ç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, operatör düzeyi NAT, link-local, çok noktaya yayın (multicast) ya da benzersiz yerel 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: Bu uç noktaya hangi olayların ulaştığı: `OpenEmail\Constants\WebhookEvents` içindeki değerlerden herhangi biri. `create`, diziyi 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 null olarak saklanır ve döndürülür. null geçirmek yerine anahtarı belirtmeyin: istemci null'u olduğu gibi gönderir ve `create` onu 422 ile reddeder.
addressAllowlistarray: 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: 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.
apiKeystring: Dizinin içindeki bir anahtar değil, dizinin yanındaki adlandırılmış bir argüman: uç noktayı istemcinin anahtarı yerine bu API anahtarıyla oluşturur.

Yanıt: oluşturulan uç nokta

camelCase anahtarlı bir dizi. 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`, `rotateSecret`, `test`, `listDeliveries`, `listAllDeliveries`, `iterateDeliveries`, `getDelivery` ve `replayDelivery`.
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 dize ile değil, bu değerle karşılaştırın.
descriptionstring or null: Verdiğiniz etiket; vermediyseniz null. `'description' => null` gönderen bir `update` onu temizler.
eventTypesarray: 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 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 null: 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 null.
disabledReasonstring or null: Sunucunun onu neden kapattığı. `disabledAt` null olduğunda her zaman null.
consecutiveFailuresint: Art arda başarısız teslimat sayısı. Teslim edilen herhangi bir olay onu 0'a sıfırlar; `enabled` değeri true olarak ayarlanmış bir `update` de öyle.
addressAllowlistarray: Bu uç noktanın haberdar olduğu tekil adresler.
domainAllowlistarray: 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 null: 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 `listDeliveries` söyler. İlk denemeye kadar null'dır, bu yüzden `create` üzerinde her zaman null'dır.
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::verifyWebhookSignature` metoduna önekiyle birlikte geçirdiğiniz değer budur. Yalnızca `create` ve `rotateSecret` 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 `rotateSecret` ile değiştirilebilir.

Günlükleri süzmek

webhook_logs.php

$failed = $client->webhooks->listWorkspaceDeliveries(status: 'failed', since: new \DateTimeImmutable('-1 day')); foreach ($failed as $delivery) {    echo $delivery['endpointId'], ' ', $delivery['eventType'], ' ', $delivery['responseCode'] ?? '-', PHP_EOL;} $history = $client->webhooks->listActivity('whe_3f9c2a7b1e4d8f60a5c7b92d'); foreach ($history as $change) {    echo $change['type'], ' ', $change['actor']['label'] ?? 'OpenEmail', PHP_EOL;}

listDeliveries tek bir uç noktayı, listWorkspaceDeliveries ise her uç noktayı ya da bir dizi veya virgülle ayrılmış tek bir dize olarak endpointIds: içinde belirtilenleri okur; ikisi de konsolun Teslimatlar sekmesindeki filtreler olan status: (delivered ya da failed), since: ve until: alır. listActivity ve listWorkspaceActivity 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 listAllDeliveries ve iterateDeliveries gibi bir listAll 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 DateTimeInterface ya da bir ISO 8601 dizesi alır; yalın bir tarih içeren bir dize o günün UTC gece yarısı anlamına gelir. until: değeri since: değerinden sonra olmalıdır; aksi hâlde çağrı, errorCode değeri invalid_parameter olan bir InvalidRequestException fırlatır.