SDK

Uç noktalar

`webhooks.list`, `get`, `create`, `update`, `delete`, `rotateSecret`, `test` ve `listDeliveries`.

Her yöntem

usage.ts

const endpoint = await openemail.webhooks.create({  url: 'https://acme.com/hooks/mail',  eventTypes: ['email.sent', 'email.bounced'],  description: 'Billing service',}) await store(endpoint.secret) await openemail.webhooks.list()await openemail.webhooks.get(endpoint.id)await openemail.webhooks.update(endpoint.id, { enabled: false })await openemail.webhooks.test(endpoint.id)const rotated = await openemail.webhooks.rotateSecret(endpoint.id)await openemail.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. Sonradan eklenenler dahil her olayı almak için eventTypes'ı atlayın.

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

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.

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

webhook-test.ts

const result = await openemail.webhooks.test('whe_…')console.log(result.delivery?.status, result.delivery?.responseCode) const deliveries = await openemail.webhooks.listDeliveries('whe_…')for (const d of deliveries) console.log(d.eventType, d.status, d.responseCode, d.error)

null 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 payload.id olaydır, deneme numarası ise denemedir.

Parametreler: webhooks.create

urlstringzorunlu: 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.
eventTypesWebhookEvent[]: 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 ya da suppression 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.
descriptionstring: 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

object'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.
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` ve `listDeliveries`.
urlstring: 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.
descriptionstring | null: Ona verdiğiniz etiket ya da hiç vermediyseniz null. Açıkça null gönderen bir `update`, değeri yeniden null'a temizler.
eventTypesWebhookEvent[] | ['*']: 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 üç ileti olayını temsil eder. `create` ve `update` yalnızca birebir olay adlarını kabul eder.
enabledboolean: 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.
lastDeliveryAtstring | 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 damgalanır; yani size uç noktanın denendiğini söyler, nasıl gittiğini ise `listDeliveries` söyler. İlk denemeye kadar null'dur ve bu yüzden `create`'te her zaman null olur.
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` değerini imzalayan HMAC-SHA-256 anahtarı: `whsec_` ve ardından base64url biçiminde 32 rastgele bayt; `verifyWebhookSignature`'a verdiğiniz şey de budur. Yalnızca `create` ve `rotateSecret` 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 `rotateSecret` ile değiştirilebilir ve bu da eskisini anında geçersiz kılar.