Webhook'ları Yapılandırma

Published: 16 Temmuz 2026 · Last updated: 21 Temmuz 2026 · By Marcus Biel

Webhook'lar, hesabınızda önemli bir şey olduğunda Maildroppa'nın başka bir uygulamaya bildirim göndermesini sağlar.

Bir abonenin oluşturulup oluşturulmadığını, güncellenip güncellenmediğini, abonelikten çıkıp çıkmadığını veya bir etiket atanıp atanmadığını Maildroppa'ya tekrar tekrar sormak yerine uygulamanız, olay gerçekleştikten kısa süre sonra bir HTTPS isteği alabilir.

Webhooks sayfası, hesap genelindeki bu entegrasyonun merkezi alanıdır. Birden fazla uç nokta oluşturabilir, her uç noktanın alacağı olayları seçebilir, kimlik doğrulama başlıkları ekleyebilir, bağlantıyı test edebilir, teslimat denemelerini inceleyebilir ve gerektiğinde bir üretim olayını yeniden oynatabilirsiniz.

Hesap Webhook'ları Nasıl Çalışır

Bir hesap webhook'u şu süreci izler:

1. Maildroppa'da bir olay gerçekleşir; örneğin bir abone oluşturulur.
2. Maildroppa, bu olaya abone olan tüm etkin uç noktaları bulur.
3. Maildroppa, eşleşen her uç nokta için bir teslimat oluşturur.
4. JSON yükü, hesabınızın webhook Signing secret'ı ile imzalanır.
5. Maildroppa, kaydedilmiş uç nokta URL'sine bir HTTPS POST isteği gönderir.
6. Uç noktanız imzayı doğrular, olayı kaydeder veya işler ve bir HTTP yanıtı döndürür.
7. Maildroppa sonucu Delivery history bölümüne kaydeder ve geçici hataları otomatik olarak yeniden dener.

Birden fazla uç nokta aynı olaya aboneyse her uç nokta kendi teslimatını alır. Business event hepsi için aynı Event ID'ye sahipken her teslimatın kendi Delivery ID'si vardır.

Hesap webhook'ları, Automation içindeki “Send a webhook” adımından farklıdır. Hesap webhook'ları Maildroppa genelindeki seçili hesap olaylarını dinler. Automation webhook'u yalnızca bir abone ilgili adıma ulaştığında gönderilir. Her ikisi de hesabın webhook Signing secret'ını kullanır; bu nedenle secret'ı döndürmek, Maildroppa imzalarını doğrulayan tüm giden webhook alıcılarını etkiler.

Webhooks Sayfasını Açma

“Settings” bölümünü açın, “Developers”ı genişletin ve “Webhooks”ı seçin.

Sayfada üç ana alan bulunur:

• Signing secret
• Endpoints
• Seçili uç nokta için Delivery history

Birden fazla uç noktanız olduğunda, Delivery history bölümünü görüntülemek için bir uç nokta satırı seçin. Açıkça bir seçim yapmadıysanız Maildroppa listedeki ilk uç noktanın geçmişini gösterir.

Uç Nokta Oluşturmadan Önce

Maildroppa'yı yapılandırmadan önce sunucunuzda bir alıcı hazırlayın. Alıcı:

• Genel erişime açık bir HTTPS URL'si üzerinden kullanılabilir olmalıdır.
• application/json gövdeli POST isteklerini kabul etmelidir.
• Maildroppa imzası doğrulanana kadar ham istek gövdesini korumalıdır.
• Yalnızca olay güvenli şekilde kabul edildikten sonra 2xx durum kodu döndürmelidir.
• Event ID'yi kullanarak tekrarlanan teslimatları idempotent şekilde işlemelidir.
• İstek sırasında yavaş işlemler yapmak yerine hızlı yanıt vermelidir.

Güvenilir bir yaklaşım; isteği doğrulamak, Event ID'yi ve yükü kalıcı bir kuyruğa veya veritabanına kaydetmek, 200 ya da 204 döndürmek ve iş aksiyonunu daha sonra gerçekleştirmektir.

Bir geliştirme bilgisayarını, yerel ağ adresini veya korumasız bir betiği üretim webhook alıcısı olarak açığa çıkarmayın. Maildroppa yalnızca genel erişime açık HTTPS hedeflerini kabul eder ve teslimat gönderilirken hedefi yeniden kontrol eder.

1. Adım: Signing Secret Oluşturma

---

Her Maildroppa webhook isteği imzalanır. Alıcınız, isteğin Maildroppa tarafından oluşturulduğunu ve gövdenin aktarım sırasında değiştirilmediğini doğrulamak için Signing secret'ı kullanır.

Sayfanın üst kısmındaki Signing secret paneli şu durumlardan birini gösterir:

• Missing — Henüz bir Signing secret mevcut değil.
• Ready — Bir Signing secret yapılandırılmış.
• Loading — Maildroppa mevcut durumu alıyor.

Durum Missing olduğunda “Generate secret” düğmesine tıklayın.

Maildroppa yeni secret'ı hemen gösterir. Secret whsec_ ile başlar. “Copy” düğmesine tıklayın ve alıcınızın kullandığı secret yöneticisinde veya korumalı ortam yapılandırmasında saklayın.

Tam değer yalnızca oluşturma veya döndürme işleminden hemen sonra gösterilir. Sayfayı yeniden yüklediğinizde veya sayfadan ayrıldığınızda Maildroppa yalnızca bir secret'ın mevcut olduğunu ve son güncellenme zamanını gösterir. Saklanan secret'ı tekrar göstermez.

Secret'ı Kaybederseniz

Alıcıda artık güncel secret yoksa “Rotate secret” düğmesine tıklayın ve görüntülenen yeni değeri kaydedin.

Döndürme işlemi önceki secret'ı hemen değiştirir. Maildroppa, geçiş süresi boyunca her iki değeri saklamaz. Yeni testler göndermeden veya üretim teslimatlarına güvenmeden önce bu hesap secret'ını kullanan tüm alıcıları güncelleyin.

Yeni teslimatlar, planlanmış yeniden denemeler, testler ve yeniden oynatmalar, HTTP isteği sırasında geçerli olan secret ile imzalanır. Bu nedenle döndürmeden önce oluşturulan bir teslimat, daha sonra denendiğinde yeni secret ile imzalanabilir.

Secret'a Parola Gibi Davranın

Signing secret'ı tarayıcı koduna, herkese açık bir depoya, URL'ye, hata sayfasına veya sıradan bir uygulama günlüğüne koymayın.

Secret'a yalnızca sunucu tarafındaki alıcının ihtiyacı vardır. Secret'ın açığa çıktığını düşünüyorsanız hemen döndürün ve tüm alıcıları güncelleyin.

Webhook İmzasını Doğrulama

Her istek şu Maildroppa başlıklarını içerir:

• X-Maildroppa-Event-Id — Business event'i tanımlar.
• X-Maildroppa-Delivery-Id — Bu özel teslimatı tanımlar.
• X-Maildroppa-Timestamp — Unix saniyesi olarak imzalama zamanı.
• X-Maildroppa-Signature — Sürümlendirilmiş HMAC imzası.

Maildroppa ayrıca şunları gönderir:

• Content-Type: application/json
• User-Agent: Maildroppa-Webhooks/1.0

İmza şu biçimdedir:

v1=<lowercase hexadecimal HMAC>

Maildroppa bunu HMAC-SHA256 ile oluşturur. İmzalanan içerik, bir nokta ve ardından tam ham JSON istek gövdesi gelen timestamp'ten oluşur:

<timestamp>.<raw request body>

HMAC anahtarı olarak Signing secret'ı kullanın.

Aşağıdaki Node.js örneği temel doğrulama adımını gösterir. rawBody, önceden ayrıştırılıp yeniden serileştirilmiş JSON değil, özgün istek baytları olmalıdır.

import crypto from 'node:crypto';

export function verifyMaildroppaWebhook({ rawBody, timestamp, signature, signingSecret }) {
  const signedPayload = Buffer.concat([Buffer.from(`${timestamp}.`, 'utf8'), rawBody]);

  const expectedSignature = `v1=${crypto
    .createHmac('sha256', signingSecret)
    .update(signedPayload)
    .digest('hex')}`;

  const received = Buffer.from(signature, 'utf8');
  const expected = Buffer.from(expectedSignature, 'utf8');

  return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}

İmzayı doğruladıktan sonra timestamp'i sunucu zamanınızla da karşılaştırın. Altyapınız için seçtiğiniz kısa bir toleransın, örneğin beş dakikanın, dışındaki istekleri reddedin. Bu, ele geçirilmiş geçerli bir isteğin çok daha sonra yeniden oynatılması riskini azaltır.

JSON'u yalnızca her iki kontrol de başarılı olduktan sonra ayrıştırıp işleyin.

İmza Hatalarının Yaygın Nedenleri

İmza genellikle şu nedenlerden biriyle başarısız olur:

• Alıcı, döndürme işleminden sonra eski bir secret kullanır.
• Middleware, imza hesaplanmadan önce JSON'u ayrıştırmış veya değiştirmiştir.
• Alıcı yalnızca gövdeyi imzalar ve <timestamp>. kısmını atlar.
• Timestamp, tam header değeri yerine biçimlendirilmiş bir tarih olarak ele alınır.
• Karşılaştırmada v1= ön eki atlanır.
• Hesaplanan HMAC, küçük harfli onaltılık yerine farklı şekilde kodlanır.

Doğrulama başarısız olduğunda Event ID ve Delivery ID'yi günlüğe kaydedin; ancak Signing secret'ı veya hassas özel başlık değerlerini asla kaydetmeyin.

2. Adım: Uç Nokta Ekleme

---

Endpoints bölümünde “Add endpoint” düğmesine tıklayın.

Düzenleyici dört bölüm içerir:

• Endpoint URL
• Events
• Custom headers
• Active status

Yeni uç noktalar Active olarak başlar ve düzenleyicide gösterilen tüm olaylar başlangıçta seçilidir. Kaydetmeden önce seçimi gözden geçirin; böylece alıcı yalnızca gerçekten ihtiyaç duyduğu bildirimleri alır.

Uç Nokta URL'sini Yapılandırma

Maildroppa isteklerini alacak eksiksiz genel URL'yi girin; örneğin:

https://integrations.example.com/webhooks/maildroppa

URL şu gereksinimleri karşılamalıdır:

• https:// kullanmalıdır.
• Geçerli bir genel hostname içermelidir.
• Uzunluğu 2.048 karaktere kadar olabilir.
• { veya } içeren template variable'lar barındıramaz.
• Hostname'den önce kullanıcı adı veya parola içeremez.
• # ile başlayan bir URL fragment'ı içeremez.
• Standart HTTPS portu olan 443ü kullanmalıdır.
• localhost, ham IP adresi veya engellenmiş özel ya da ayrılmış bir ağa çözümlenen hostname kullanamaz.

Sorgu parametreleri desteklenir; ancak API anahtarlarını veya diğer secret'ları URL'ye koymayın. URL'ler uç nokta listesinde ve teslimat verilerinde görünür. Kimlik bilgileri için bunun yerine Custom header kullanın.

Maildroppa yönlendirmeleri takip etmez. 301, 302, 307 veya 308 döndüren bir URL yerine son HTTPS hedefini kaydedin.

Hedef hostname'i gönderimden önce yeniden çözümlenir. Daha sonra özel veya engellenmiş bir adrese çözümlenen bir hostname, uç nokta kaydedildiğinde geçerli olsa bile reddedilir.

Olayları Seçme

En az bir olay seçin. Bir uç nokta yalnızca düzenleyicisinde seçilen olay türlerini alır.

Sayfada şu olay seçenekleri sunulur:

Subscriber Created — subscriber.created

Maildroppa hesabında bir abone oluşturulduğunda gönderilir.

Bu olayı, ilgili kişiyi bir CRM'ye, müşteri veri platformuna, dahili veritabanına veya izinleri dikkate alan başka bir sisteme eklemek için kullanın.

Bu olayı, her kaydın Double Opt-in sürecini tamamladığının kanıtı olarak yorumlamayın. Yükteki abone durumu mevcut durumu açıklar.

Subscriber Updated — subscriber.updated

Yerleşik abone bilgileri veya özel alan değerleri değiştiğinde gönderilir.

Yükteki eksiksiz abone nesnesini mevcut Maildroppa gösterimi olarak kullanın. Yalnızca belirli bir özelliğin değiştiğini varsaymaktan kaçının.

Etiket atamaları ve kaldırmaları kendi olay türlerine sahiptir; böylece ayrı ayrı işlenebilirler.

Subscriber Unsubscribed — subscriber.unsubscribed

Abone bir abonelikten çıkma işlemiyle unsubscribed durumuna geçtiğinde gönderilir.

Bağlı sistemlerde ilgili kişiyi bastırmak için bu olayı kullanın. Başka bir sistem kişiyi hâlâ etkin olarak işaretliyor diye kişiyi otomatik olarak yeniden abone yapmayın.

Tag Added — subscriber.tag_added

Bir aboneye etiket atandığında gönderilir.

Yük, bu özel değişiklikteki aboneyi ve ilgili etiketi içerir.

Tag Removed — subscriber.tag_removed

Bir etiket aboneden kaldırıldığında gönderilir.

Yük, güncellenmiş aboneyi ve kaldırılan etiketi içerir. Kaldırılan etiket abonenin mevcut tags dizisinde artık yer almasa da ayrıca sağlanır.

Form Submitted — form.submitted

Bir ziyaretçi Maildroppa signup form'unu gönderdiğinde gönderilir.

Bunu, Double Opt-in'in tamamlandığının onayı olarak değil, form gönderim sinyali olarak değerlendirin. Onaylanmış abonelik gerektiren iş akışları, abonenin mevcut durumuna ve onay sürecine uymaya devam etmelidir.

Sorumluluklar Farklıysa Ayrı Uç Noktalar Kullanın

Farklı olayları farklı sistemlere gönderebilirsiniz. Örneğin:

• Abone ve etiket olaylarını bir CRM'ye gönderin.
• Abonelikten çıkma olaylarını bir suppression service'e gönderin.
• Form gönderim olaylarını bir analytics pipeline'a gönderin.

Ayrı uç noktalar gereksiz trafiği azaltır ve hataların teşhisini kolaylaştırır. Her uç noktanın kendi olay seçimi, URL'si, özel başlıkları, etkin durumu, testleri ve Delivery history'si vardır.

Özel Başlıklar Ekleme

Özel başlıklar isteğe bağlıdır. Alıcı bir API anahtarı, bearer token, tenant identifier veya başka bir sabit header gerektirdiğinde kullanın.

“Add header” düğmesine tıklayın, ardından Header name ve Header value alanlarını doldurun. Uygun örnekler:

Authorization: Bearer your-token

X-Integration-Key: your-secret-key

En fazla 20 özel başlık ekleyebilirsiniz.

Başlık adları:

• Zorunludur.
• 128 karaktere kadar olabilir.
• Geçerli HTTP header-name karakterlerini kullanmalıdır.
• Büyük/küçük harf farkı gözetilmeksizin benzersiz olmalıdır.

Başlık değerleri:

• Zorunludur.
• 2.000 karaktere kadar olabilir.
• Satır sonu içeremez.

Aşağıdaki adlar ayrılmıştır ve özel bir başlıkla değiştirilemez:

• Content-Type
• Content-Length
• Host
• User-Agent
• X-Maildroppa- ile başlayan tüm adlar

Bu, özel bir değerin Maildroppa'nın teslimat ve imza başlıklarının yerini almasını önler.

Header Secret'ları Nasıl Saklanır?

Maildroppa, özel başlık değerlerini saklamadan önce şifreler. Kaydedilen değerler tarayıcıya okunabilir biçimde geri gönderilmez.

Uç noktayı daha sonra düzenlediğinizde değer alanında “Stored value kept” gösterilir. Mevcut secret'ın değiştirilmeden kalmasını istiyorsanız alanı boş bırakın. Değiştirmek için yeni bir değer girin.

Başlık adını değiştirirseniz değeri yeniden girin. Maildroppa, saklanan secret'ı yalnızca özgün başlık adı değişmeden kaldığı sürece korur.

Bir başlık satırını kaldırmak, uç nokta kaydedildikten sonra bu başlığı gelecekteki teslimatlardan kaldırır.

Özel başlık değerleri saklanan istek bilgilerinde hassas kabul edilir. Delivery history bölümünde görüntülenmek yerine maskelenir.

Uç Noktayı Active veya Inactive Yapma

Uç noktanın hemen olay almaya hazır olduğu durumda “Active” seçili kalsın.

Teslimatları başlatmadan yapılandırmayı kaydetmek istediğinizde seçimi kaldırın. Uç noktayı daha sonra uç nokta listesinden etkinleştirebilirsiniz.

Inactive bir uç nokta:

• Yeni gerçekleşen olayları almaz.
• Test webhook'u gönderemez.
• Görünür ve düzenlenebilir kalır.
• Mevcut Delivery history'sini erişilebilir tutar.

Bir uç noktayı etkinleştirmek, etkin değilken gerçekleşen olayları geriye dönük olarak doldurmaz.

URL, olay seçimi, başlıklar ve durum doğru olduğunda “Save” düğmesine tıklayın.

Uç Nokta Listesini Anlama

Her uç nokta satırı şunları gösterir:

• Hedef URL.
• Active veya Inactive rozeti.
• Abone olunan olay türleri.
• Özel başlık sayısı.
• Uç noktanın son güncellenme zamanı.

Kullanılabilir aksiyonlar:

• On/Off — Uç noktayı etkinleştirir veya devre dışı bırakır.
• Test — Etkin bir uç noktaya hemen bir test isteği gönderir.
• Edit — URL'yi, olayları, başlıkları veya etkin durumunu değiştirir.
• Delete — Onaydan sonra uç nokta yapılandırmasını kalıcı olarak kaldırır.

O uç noktanın Delivery history'sini listenin altında açmak için satırın ana bölümünü seçin.

Kaydedilen Değişiklikler Mevcut Teslimatları Nasıl Etkiler?

Bir hesap olayı, o andaki uç nokta URL'sinin, yükün ve özel başlıkların anlık görüntüsünü içeren bir teslimat oluşturur.

URL'yi veya özel başlıkları düzenlemek, yeni oluşturulan teslimatları etkiler. Zaten kuyruğa alınmış bir teslimat özgün hedefini ve saklanan başlık yapılandırmasını korur.

Seçili olayları değiştirmek de yalnızca bundan sonra gerçekleşen olayları etkiler. Maildroppa, olay gerçekleştiğinde seçili olmayan olay türleri için geriye dönük teslimatlar oluşturmaz.

Signing secret farklıdır: HTTP isteği hazırlanırken okunur. Bu nedenle bekleyen bir teslimat veya replay, yükü ve uç nokta anlık görüntüsü daha önce oluşturulmuş olsa bile yeni döndürülmüş Signing secret'ı kullanabilir.

Uç Noktayı Test Etme

Alıcı ve Signing secret hazır olduğunda etkin bir uç noktada “Test” düğmesine tıklayın.

Maildroppa, kaydedilmiş uç nokta URL'sini ve özel başlıkları kullanarak hemen imzalı bir istek gönderir. Açık bir düzenleyicide kaydedilmemiş değişiklikler teste dahil edilmez.

Test yükü webhook.test olay türünü kullanır ve livemode değerini false olarak ayarlar:

{
  "id": "evt_test_example",
  "type": "webhook.test",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": false,
  "data": {
    "message": "This is a test webhook from Maildroppa."
  }
}

Oluşturulan ID'ler ve timestamp her gerçek testte farklıdır.

Bir test tam olarak bir HTTP denemesi yapar. Test teslimatları üretim yeniden deneme programına alınmaz ve yeniden oynatılamaz.

İstek tamamlandıktan sonra sonuç paneli şunları gösterir:

• Test success veya Test failed
• Event ID
• Yanıt alındığında HTTP status
• Duration
• Delivery ID
• Kullanılabilir olduğunda hata bilgileri
• Alıcı bir gövde döndürdüğünde response excerpt

Test ayrıca Delivery history'de Test rozetiyle görünür. Yalnızca test isteklerini göstermek için “Test” filtresini kullanın.

Üretim Yükünü Anlama

Üretim hesap olayları ortak bir JSON zarfı kullanır:

{
  "id": "evt_example",
  "type": "subscriber.created",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": true,
  "data": {}
}

Üst düzey özelliklerin anlamları:

• id — Event ID. X-Maildroppa-Event-Id ile eşleşir.
• type — Uç nokta düzenleyicisinde seçilen olay anahtarı.
• schema_version — Yük şeması sürümü. Olayı nasıl ayrıştıracağınıza karar verirken kullanın.
• created_at — Olay yükünün oluşturulduğu zaman, UTC olarak.
• livemode — Üretim olayları için true, test olayları için false.
• data — Olaya özgü içerik.

Olayları tam type değerine göre yönlendirin. Entegrasyonunuzun ihtiyaç duymadığı ek özellikleri yok sayın; böylece uyumlu yük eklemeleri alıcıyı bozmaz.

Abone Olayı Yükü

Abone olayları, mevcut abone gösterimini data.subscriber içinde içerir:

{
  "id": "evt_example",
  "type": "subscriber.updated",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": true,
  "data": {
    "subscriber": {
      "id": "7f49d0e9-77d6-4c24-8b90-12c9d53d82cc",
      "email": "alex@example.com",
      "first_name": "Alex",
      "status": "active",
      "registered_at": "2026-07-15T08:15:00Z",
      "fields": [
        {
          "id": "b6594e58-0c4b-4138-9ad8-fc4747e076eb",
          "personalization_tag_name": "company",
          "value": "Example Ltd."
        }
      ],
      "tags": [
        {
          "id": "c69af5de-39d3-42a4-8f55-ddf86d10a51c",
          "name": "Customers"
        }
      ]
    }
  }
}

fields ve tags dizidir. Boş olabilirler. Değer mevcut olmadığında bir abone özelliği null da olabilir; bu nedenle alıcınız her isteğe bağlı profil değerinin mevcut olduğunu varsaymak yerine yük şemasını izlemelidir.

Etiket Olayı Yükü

Etiket olayları hem aboneyi hem de olaya neden olan etiketi içerir:

{
  "id": "evt_example",
  "type": "subscriber.tag_added",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": true,
  "data": {
    "subscriber": {
      "id": "7f49d0e9-77d6-4c24-8b90-12c9d53d82cc",
      "email": "alex@example.com",
      "first_name": "Alex",
      "status": "active",
      "registered_at": "2026-07-15T08:15:00Z",
      "fields": [],
      "tags": []
    },
    "tag": {
      "id": "c69af5de-39d3-42a4-8f55-ddf86d10a51c",
      "name": "Customers"
    }
  }
}

subscriber.tag_removed için data.tag, abonenin mevcut tags dizisinde artık yer almasa bile kaldırılan etiketi tanımlamaya devam eder.

Event ID'ler, Delivery ID'ler ve Idempotency

Event ID ve Delivery ID farklı amaçlara hizmet eder.

Event ID

Event ID, business event'i tanımlar. Şuralarda görünür:

• Yükün üst düzey id özelliğinde.
• X-Maildroppa-Event-Id istek header'ında.
• Delivery history'de.

Aynı olay birden fazla abone olunan uç noktaya gönderilebilir. Bu teslimatlar Event ID'yi paylaşır.

Yeniden denemeler ve manuel replay'ler de özgün Event ID'yi korur. İşlenen Event ID'leri saklayın ve tekrarlanan bir isteğin yinelenen kişiler oluşturmasını, geri döndürülemez bir aksiyonu tekrarlamasını veya aynı değişikliği iki kez uygulamasını önlemek için iş aksiyonunu idempotent hale getirin.

Delivery ID

Delivery ID, tek bir teslimat kaydını tanımlar. Şuralarda görünür:

• X-Maildroppa-Delivery-Id istek header'ında.
• Delivery history'de.

Her uç nokta teslimatının kendi Delivery ID'si vardır. Manuel replay, özgün Event ID'yi korurken yeni bir Delivery ID oluşturur.

Teknik izleme ve destek için Delivery ID'yi kullanın. İş düzeyinde tekilleştirme için Event ID'yi kullanın.

Doğru HTTP Yanıtını Döndürme

Maildroppa yanıtları şu şekilde sınıflandırır:

• Herhangi bir 2xx yanıtı teslimatı başarılı olarak işaretler.
• 408 Request Timeout, 429 Too Many Requests ve 5xx yanıtları geçici hatalardır ve yeniden denenebilir.
• Geçici olabilecek ağ hataları yeniden denenir.
• Yönlendirmeler ve diğer 3xx yanıtları takip edilmez ve kalıcı hata olarak değerlendirilir.
• Diğer 4xx yanıtları kalıcı hata olarak değerlendirilir ve yeniden denenmez.

Yalnızca olay güvenli şekilde kabul edildiğinde 200, 202 veya 204 döndürün. İşleme zaman alıyorsa önce olayı kaydedin ve daha yavaş işi eşzamansız olarak yapmadan önce başarılı yanıt döndürün.

Başka bir webhook URL'sine yönlendirme döndürmeyin. Bunun yerine Maildroppa'da son URL'yi yapılandırın.

Otomatik Yeniden Deneme Programı

Üretim teslimatları en fazla yedi HTTP denemesi yapabilir.

Yeniden denenebilir bir hatadan sonra Maildroppa sonraki denemeyi şu gecikmelerle planlar:

1. 1. denemeden sonra: 1 dakika
2. 2. denemeden sonra: 5 dakika
3. 3. denemeden sonra: 30 dakika
4. 4. denemeden sonra: 2 saat
5. 5. denemeden sonra: 12 saat
6. 6. denemeden sonra: 24 saat

7. deneme de yeniden denenebilir bir hatayla sonuçlanırsa teslimat Dead durumuna geçer ve başka otomatik deneme planlanmaz.

Program, ayrı ayrı başarısız denemelerden itibaren ölçülür. Teslimatlar eşzamansız işlendiği ve sistem koruma limitlerine de tabi olduğu için gerçek teslimat zamanı biraz daha geç olabilir.

Mümkün olduğunda geçici alıcı sorununu gösterilen “Next retry” zamanından önce düzeltin. Otomatik denemeler sona erdiyse alıcı yeniden sağlıklı hale geldikten sonra Replay kullanın.

Delivery History'yi Anlama

Delivery history, o anda seçili olan uç noktaya aittir. Hangi geçmişi görüntülediğinizi doğrulayabilmeniz için uç nokta URL'si bölüm başlığında görünür.

Şu filtreleri kullanın:

• All — Üretim ve test teslimatlarını gösterir.
• Production — Yalnızca canlı olay teslimatlarını gösterir.
• Test — Yalnızca manuel testleri gösterir.

En güncel durumu almak için “Refresh” düğmesine tıklayın. Maildroppa bir teslimatı gönderirken veya yeniden denerken geçmişin açık tutulması gerekmez.

Sayfa, seçili filtreyle eşleşen en son 50 teslimatı gösterir.

Teslimat Sütunları

Her satır şunları içerir:

• Created — Teslimat kaydının oluşturulduğu zaman.
• State — Pending, Success, Failed veya Dead.
• HTTP — Yanıt durumu, deneme sayısı ve uygun olduğunda sonraki deneme zamanı.
• Subscriber — Olay bir aboneyle bağlantılı olduğunda abonenin e-postası.
• Delivery — Olay türü, Event ID ve Delivery ID.
• Actions — Teslimat uygun olduğunda Replay.

HTTP isteği yapılmadıysa HTTP sütununda “No HTTP attempt” gösterilir. Bu durum, örneğin Signing secret eksik olduğu veya kaydedilen hedef artık güvenli biçimde kullanılamadığı için Maildroppa'nın isteği göndermeden önce reddetmesiyle gerçekleşebilir.

Kullanılabilir olduğunda satırda alıcının döndürdüğü bir Error ve Response excerpt de gösterilir. Webhook yanıt gövdesinde secret'ları veya hassas kişisel verileri döndürmeyin; bu yanıtın bir bölümü hesabın teslimat günlüğünde görünebilir.

Teslimat Durumları

Pending, teslimatın ilk denemeyi veya planlanmış yeniden denemeyi beklediği anlamına gelir. Başka bir deneme planlandığında “Next retry” görünür.

Success, alıcının 2xx yanıtı döndürdüğü anlamına gelir. Başka otomatik deneme gerekmez.

Failed, teslimatın yeniden denenemeyen bir sorunla sona erdiği, HTTP denemesinden önce reddedildiği veya gönderilmeden önce durdurulduğu anlamına gelir.

Dead, yeniden denenebilir bir sorun için tüm otomatik denemelerin başarılı bir yanıt alınmadan kullanıldığı anlamına gelir.

Geçmiş Saklama Süresi

Teslimat kayıtları sınırlı bir süreyle saklanır:

• Başarılı üretim teslimatları: 30 gün
• Başarısız üretim teslimatları: 90 gün
• Dead üretim teslimatları: 90 gün
• Test teslimatları: 30 gün

Daha uzun bir denetim geçmişine ihtiyaç duyduğunuzda kendi entegrasyon günlüklerinizi tutun. Event ID'leri ve Delivery ID'leri saklayın; ancak secret'ları gereksiz yere saklamaktan kaçının.

Teslimatı Yeniden Oynatma

Tamamlanmış bir üretim teslimatının yeniden denenmesi gerektiğinde “Replay” düğmesine tıklayın.

Replay, Success, Failed veya Dead durumundaki üretim teslimatları için kullanılabilir. Teslimat Pending durumundayken kullanılamaz ve test teslimatları yeniden oynatılamaz.

Bir replay:

• Yeni bir Pending teslimatı oluşturur.
• Yeni bir Delivery ID oluşturur.
• Özgün Event ID'yi korur.
• Özgün olay türünü ve JSON yükünü korur.
• Özgün kaydedilmiş hedef URL'sini ve özel başlık anlık görüntüsünü kullanır.
• Yeni istek hazırlanırken geçerli Signing secret'ı kullanır.

Replay, yükü abonenin mevcut verilerinden yeniden oluşturmaz. Özgün olay anlık görüntüsünü yeniden gönderir. Bu, replay'i denetlenebilir kılar ve geçmiş bir olayın anlamının sessizce değişmesini önler.

Aynı kaynak teslimatın aynı anda yalnızca bir replay'i Pending olabilir. Başka bir replay istemeden önce bu replay'in tamamlanmasını bekleyin.

Replay yapmadan önce uç noktanın Active olduğundan emin olun. Uç nokta inactive ise kuyruğa alınmış replay başarıyla teslim edilemez.

Alıcı, Maildroppa başarı yanıtını almasa bile iş aksiyonunu tamamlamış olabileceğinden replay yinelenen bir istek oluşturabilir. Event ID tekilleştirmesi, bağlı sistemin aksiyonu tekrarlamasını önler.

Uç Noktayı Düzenleme

URL'yi, olay seçimini, özel başlıkları veya etkin durumu değiştirmek için “Edit” düğmesine tıklayın.

Kaydetmeden önce:

1. Yeni URL'nin zaten kullanılabilir olduğunu doğrulayın.
2. Değişmeden kalması gereken saklanmış başlık değerlerini boş bırakın.
3. Yeniden adlandırılan her başlık için yeni bir değer girin.
4. Gerekli bildirimlerin yanlışlıkla kaldırılmadığından emin olmak için olay seçimini gözden geçirin.
5. Kaydedin ve yeni bir Test webhook'u gönderin.

Kuyruğa alınmış teslimatların mevcut URL'lerini ve özel başlık anlık görüntülerini koruduğunu unutmayın. Gelecekteki teslimatlar için yeni yapılandırmayı test edin; eski, kuyruğa alınmış bir isteğin değiştiğini varsaymayın.

Uç Noktayı Devre Dışı Bırakma

Yapılandırmayı ve geçmişi silmeden bir entegrasyonu duraklatmak istediğinizde On/Off anahtarını kullanın.

Bir uç nokta Off durumuna getirildiğinde:

• Yeni olaylar artık bu uç nokta için kuyruğa alınmaz.
• Gönderim için henüz alınmamış Pending teslimatlar Failed olarak işaretlenir.
• Test devre dışı bırakılır.
• Uç nokta düzenleme ve daha sonra yeniden etkinleştirme için kullanılabilir kalır.

Devre dışı bırakma anında hâlihazırda devam eden bir istek tamamlanabilir. Bu ayrım entegrasyonunuz için önemliyse uç noktayı Off yaptıktan sonra Delivery history'yi kontrol edin.

Uç nokta inactive durumdayken kaçırılan olaylar, tekrar On yaptığınızda geriye dönük olarak doldurulmaz.

Uç Noktayı Silme

Uç noktanın artık var olmaması gerektiğinde “Delete” düğmesine tıklayın ve uyarıyı onaylayın.

Silme işlemi uç noktayı sayfadan kaldırır, gelecekteki olay teslimatlarını durdurur ve gönderim için henüz alınmamış bekleyen teslimatları Failed durumuna getirir.

Delete geçici duraklatma yöntemi değildir. Yapılandırmaya veya görünür geçmişine yeniden ihtiyaç duyabileceğiniz durumlarda On/Off anahtarını kullanın.

Silmeden önce entegrasyon denetiminiz için hâlâ ihtiyaç duyduğunuz Event ID'leri veya Delivery ID'leri kaydedin.

Sorun Giderme

Uç Nokta Kaydedilemiyor

Şunları kontrol edin:

• URL https:// ile başlıyor.
• URL genel bir hostname ve 443 portu kullanıyor.
• URL değişken, giriş bilgisi veya fragment içermiyor.
• En az bir olay seçili.
• Her Custom header benzersiz bir ada ve değere sahip.
• Ayrılmış Maildroppa ve HTTP başlıkları özel ad olarak kullanılmıyor.

Test Devre Dışı

Test yalnızca Active bir uç nokta için kullanılabilir. Uç noktayı On konumuna getirin veya düzenleyip “Active” seçin; ardından test etmeden önce kaydedin.

Testte HTTP Denemesi Görünmüyor

Durum Missing ise bir Signing secret oluşturun. Ayrıca hedef hostname'in genel erişime açık olup olmadığını ve hâlâ doğru şekilde çözümlendiğini kontrol edin.

Secret, URL, özel başlıklar veya hedef güvenliği kontrolü geçersiz olduğunda istek gönderilmeden önce reddedilebilir.

Alıcı 401 veya 403 Döndürüyor

Kaydedilen Custom header adını ve kimlik bilgisini kontrol edin. Değiştiyse uç noktayı düzenleyin ve değeri yeniden girin.

Ayrıca alıcının kendi API kimlik bilgisini Maildroppa imzasıyla karıştırmadığından emin olun. Özel bir authorization header ile X-Maildroppa-Signature farklı amaçlara hizmet eder ve birbirinden bağımsız kontrol edilebilir.

Alıcı Yönlendirme Döndürüyor

Maildroppa yönlendirmeleri takip etmez. Uç nokta URL'sini son genel HTTPS URL'siyle değiştirin ve tekrar test edin.

İmza Eşleşmiyor

Alıcının şunları yaptığını doğrulayın:

• Güncel Signing secret'ı kullanıyor.
• Tam X-Maildroppa-Timestamp değerini kullanıyor.
• <timestamp>.<raw request body> ifadesini imzalıyor.
• HMAC-SHA256 ve küçük harfli onaltılık çıktı kullanıyor.
• v1= dahil tam değeri karşılaştırıyor.
• JSON ayrıştırma gövdeyi değiştirmeden önce karşılaştırma yapıyor.

Aynı Olay Birden Fazla Kez Geliyor

Bu durum ağ kesintisi, yeniden deneme veya manuel replay sonrasında gerçekleşebilir. Webhook teslimat sistemlerinin tam olarak bir kez teslimat yerine en az bir kez teslimat sağlaması normaldir.

Event ID'yi idempotency key olarak kullanın. Daha önce işlenmiş bir Event ID yeniden alındığında ve ek işlem gerekmediğinde 2xx yanıtı döndürün.

Teslimat Pending Durumunda

HTTP sütunundaki “Next retry” bilgisine bakın. Yeniden denenebilir bir 408, 429, 5xx veya geçici ağ hatası, bir sonraki planlanmış denemeye kadar Pending durumunda kalır.

Yeniden deneme zamanından sonra en güncel durumu yüklemek için “Refresh” düğmesine tıklayın.

Teslimat Dead Durumunda

Tüm otomatik denemeler kullanılmıştır. Önce alıcıyı düzeltin, uç noktanın Active olduğundan emin olun, bir Test webhook'u gönderin ve ardından üretim teslimatında Replay kullanın.

Önerilen Üretim Kontrol Listesi

Üretimde bir uç noktaya güvenmeden önce aşağıdakilerin tümünü doğrulayın:

1. Alıcı, geçerli sertifikaya sahip, kararlı ve genel erişime açık bir HTTPS URL'si kullanıyor.
2. Signing secret kaynak kodu dışında saklanıyor.
3. İmza, değiştirilmemiş ham gövdeyle karşılaştırılıyor.
4. Eski timestamp'ler belgelenmiş bir toleransa göre reddediliyor.
5. Alıcı Event ID'leri saklıyor ve tekilleştiriyor.
6. Alıcı izleme için Event ID'leri ve Delivery ID'leri günlüğe kaydediyor.
7. Yavaş işleme, olay kalıcı olarak kabul edildikten sonra gerçekleşiyor.
8. 2xx yanıtı yalnızca kabul edilen olaylar için döndürülüyor.
9. Özel kimlik bilgileri URL yerine başlıklarda saklanıyor.
10. Yalnızca gerekli olay türleri seçiliyor.
11. Bir Test webhook'u başarıyla tamamlanıyor ve Delivery history'de doğru şekilde görünüyor.
12. Üretim teslimatları hata döndürmeye başladığında izleme sistemi sizi uyarıyor.

Bu önlemler alındığında Webhooks sayfası güvenilir bir entegrasyonun her iki tarafını da sunar: uygulamanıza güvenli olay teslimatı ve Maildroppa içinde anlaşılır bir operasyon geçmişi.