Webhook
Genel Bakış
Amacı Nedir?
Webhook Connection (Bağlantı) tanımını merkezi hale getirerek tüm Integration Flow ve Connector adımlarının aynı HTTP uç noktasını tutarlı şekilde çağırmasını sağlar
HTTP metodunu, URL'yi ve güvenlik başlıklarını tek noktadan yöneterek sürüm geçişlerinde yapılandırma hatalarını azaltır
Ortam bazlı bağlantı parametreleri sayesinde Development/Test/Production uç noktalarını tek connection içinde ayırır
Otomatik isim kontrolü, environment dağıtımı ve Test Connection çıktıları ile devreye alma süreçlerini hızlandırır
Çalışma Prensibi
Integration Flow veya Connector içerisinden Webhook bağlantısı talep edildiğinde, sistem yapılandırılmış connection parametrelerini okur
Bağlantı havuzu her zaman etkindir, bir aç/kapa anahtarı yoktur; Host Başına ve Toplam bağlantı sayısı üst sınırları dahilinde açık bağlantılar yeniden kullanılır, sınır dolduğunda yeni istek boş bir bağlantı için bekler
Header sekmesinde tanımlanan Authorization, Api-Key veya benzeri Authentication başlıkları otomatik olarak isteğe eklenir
Seçilen HTTP metodu ile REST API çağrısı yapılır, yük (payload) Integration Flow adımının çıktısından alınır ve TLS üzerinden iletilir
İstek tamamlandığında soket kapatılır veya HTTP keep-alive süresi içinde yeniden kullanılmak üzere bekletilir
Bağlantı hatası, timeout veya authentication hatası durumunda hata Apinizer Message Service üzerinden kullanıcıya bildirilir ve deploymentResult loglarına yazılır
Kullanım Alanları
Apinizer loglarını Splunk, Datadog, Graylog gibi gözlemleme platformlarına REST webhook üzerinden aktarmak
CI/CD pipeline'larında başarılı deployment sonrası Slack veya Teams kanalını tetiklemek
Dış servislerden gelen olayları MongoDB/Redis yerine üçüncü taraf webhook API'lerine yönlendirmek
Hızlı prototiplerde dış SaaS servislerine POST/PUT çağrısı yapmak
Teknik Özellikler ve Yetenekler
Temel Özellikler
EnumHttpRequestMethod listesindeki GET/POST/PUT/DELETE vb. tüm metotlar tek dropdown üzerinden seçilir.
Tam URL (fullUrl) alanı ile https://host/path biçimindeki uç nokta tanımlanır ve Integration Flow parametreleriyle birleştirilebilir.
Öntanımlı HTTP header adı/değer servisleri sayesinde otomatik tamamlama yapılır ve hatalı başlık girme riski düşer.
Her ortam (Development, Test, Production) için ayrı connection parametreleri tanımlama imkanı.
Connection'ı aktif veya pasif hale getirme (enable/disable toggle). Pasif durumda bağlantı kullanılamaz ancak yapılandırması saklanır.
Host başına ve toplam bağlantı sayısı ayrı ayrı sınırlandırılabilir; güven deposu ve istemci sertifikası tanımlanarak karşı taraf ve mTLS doğrulaması yapılabilir.
Bağlantı kurma, yanıt bekleme ve gövde gönderimi için ayrı zaman aşımı süreleri tanımlanabilir.
Olaylar tek istekte toplu gönderilebilir, gzip ile sıkıştırılabilir ve Splunk HEC uç noktasına doğrudan zarflanarak iletilebilir.
İleri Düzey Özellikler
Name alanı girilirken servis tabanlı nameExist kontrolü çalışır ve çakışmalar anında gösterilir.
Eksik ad/değer bırakılan başlıklar kaydetme sırasında engellenir.
List view üzerinden Move to Global aksiyonu ile connection tüm projeler tarafından kullanılabilir hale getirilir.
"Test Connection" butonu ile bağlantı parametrelerini kaydetmeden önce doğrulama imkanı.
Connection yapılandırmasını ZIP dosyası olarak export etme. Farklı ortamlara (Development, Test, Production) import etme. Versiyon kontrolü ve yedekleme imkanı.
Bağlantı sağlığı ve performans metriklerini izleme.
Connection Parametreleri
Zorunlu Parametreler
Açıklama: Connection adı (benzersiz olmalı)
Örnek Değer: Production_Webhook
Notlar: Boşlukla başlamaz, özel karakter kullanılmaz
Açıklama: Connection'ın bağlı olacağı yayınlanmış ortam kimliği
Örnek Değer: Prod-Blue
Notlar: Environment listesi EnvironmentService tarafından doldurulur
Açıklama: Çağrıda kullanılacak HTTP metodu
Örnek Değer: POST
Notlar: GET/POST/PUT/DELETE/HEAD/OPTIONS/PATCH/TRACE desteklenir
Açıklama: Webhook uç noktasının tam URL'si
Örnek Değer: https://hooks.partner.com/api/logs
Notlar: HTTPS kullanılması önerilir, query parametreleri desteklenir
Açıklama: İsteğin zaman aşımı süresi (sn)
Örnek Değer: 10
Notlar: UI'da minimum 1 sn, model varsayılan 2 sn
İsteğe Bağlı Parametreler
Açıklama: Connection'ın amacı veya hedef sistemi açıklayan metin
Varsayılan Değer: -
Önerilen Değer: Kısa ve eyleme dönük açıklama
Açıklama: Webhook çağrısında gönderilecek özel HTTP başlıkları
Varsayılan Değer: (Boş liste)
Önerilen Değer: Authorization: Bearer token gibi güvenlik başlıkları
Açıklama: Connection'ın aktif olup olmadığı
Varsayılan Değer: true
Önerilen Değer: Test aşamasında false, Production'da true
Timeout ve Connection Pool Parametreleri
Bağlantı Kurma, Yanıt, Bağlantı İsteği ve Soket süreleri boş bırakılırsa üstteki zorunlu Timeout alanına (varsayılan 2 saniye) düşer. Gövde Gönderim Fren Süresi bu ortak fallback’e dahil değildir; kendi bağımsız varsayılanı (30 saniye) vardır.
Açıklama: TCP bağlantısının kurulması için beklenecek süre; alan adı connectTimeoutSeconds
Varsayılan: 2 (boş bırakılırsa üstteki Timeout alanına düşer)
Min: 1
Birim: saniye
Açıklama: Sunucudan yanıtın tamamlanması için beklenecek süre; alan adı responseTimeoutSeconds
Varsayılan: 2 (boş bırakılırsa üstteki Timeout alanına düşer)
Min: 1
Birim: saniye
Açıklama: Havuzdan boş bir bağlantı alınması için beklenecek süre; alan adı connectionRequestTimeoutSeconds
Varsayılan: 2 (boş bırakılırsa üstteki Timeout alanına düşer)
Min: 1
Birim: saniye
Açıklama: Veri okuma/yazma sırasında soket üzerinde beklenecek süre; alan adı socketTimeoutSeconds
Varsayılan: 2 (boş bırakılırsa üstteki Timeout alanına düşer)
Min: 1
Birim: saniye
Açıklama: İstek gövdesinin gönderimi bu süreyi aşarsa istek iptal edilir; alan adı writeStallTimeoutSeconds
Varsayılan: 30
Min: 1
Birim: saniye
Not: 0 veya altı verilirse bu koruma devre dışı kalır (sınırsız blok)
Açıklama: Aynı hedef host'a açılabilecek maksimum eşzamanlı bağlantı sayısı
Varsayılan: 24
Kural: En az 1 olmalı
Birim: adet
Açıklama: Bu Connection için havuzdaki maksimum toplam bağlantı sayısı
Varsayılan: 48
Kural: Host başına değerinden küçük girilebilir, UI bunu engellemez; çalışma zamanında host başına değerine yukarı çekilir (clamp) ve bu durum WARN olarak loglanır
Birim: adet
Bağlantı havuzu parametreleri (host başına / toplam) daha önce de vardı ancak ekranda ayarlanamıyordu; her Webhook bağlantısı için artık ayrı ayrı yapılandırılabilir. Boş bırakıldığında yukarıdaki varsayılan değerler kullanılır.
TLS ve Güven Deposu
Açıklama: Webhook uç noktasının sunucu sertifikasını doğrulamak için kullanılacak güven deposu
Varsayılan: Seçili değil
Açıklama: Karşı tarafın mutual TLS (mTLS) beklediği durumlarda sunulacak istemci sertifikası
Varsayılan: Seçili değil
Açıklama: Sertifikadaki ana bilgisayar adının hedef URL ile eşleşip eşleşmediğinin kontrol edilmesi
Varsayılan: Kapalı
Güven deposu seçilmediğinde webhook uç noktasının sunucu sertifikası doğrulanmaz; bu, önceki davranışın aynen korunmasıdır ve bu durum bir uyarı olarak loglanır. Kişisel veri içeren trafik kayıtlarını HTTPS ile dışarı gönderen kurumların bir güven deposu tanımlaması önerilir. SSLv3 ve TLSv1/TLSv1.1 artık desteklenen protokoller arasında değildir.
Toplu Gönderim ve Sıkıştırma
Toplu gönderim varsayılan olarak kapalıdır; açılmadığı sürece her olay bugünkü gibi tek tek gönderilir.
Toplu gönderim açıldığında olaylar bir tampon üzerinde biriktirilir ve üç tetikleyiciden biri dolduğunda (olay sayısı, bayt boyutu veya bekleme süresi) tek istekte satır satır JSON biçiminde gönderilir.
Açıklama: Olayların tek istekte toplu gönderilip gönderilmeyeceği
Varsayılan: Kapalı
Açıklama: Tek bir toplu istekte gönderilecek en fazla olay sayısı
Varsayılan: 100
Açıklama: Tek bir toplu istekteki en fazla gövde boyutu
Varsayılan: 1 MB
Açıklama: İlk olay tampona girdikten sonra gönderimin geciktirilebileceği en fazla süre
Varsayılan: 200 milisaniye
Açıklama: Toplu gönderim tamponunun bayt cinsinden üst sınırı
Varsayılan: 32 MB
Açıklama: Gönderilen gövdenin gzip ile sıkıştırılıp sıkıştırılmayacağı
Varsayılan: Kapalı
Açıklama: Tampon doluyken gönderen tarafın bekleyeceği en fazla süre. Bu süre dolduğunda kayıt, tanımlıysa failover connector'a yönlendirilir; failover tanımlı değilse düşürülür. Toplu gönderimdeki bekleme süresinden bağımsız çalışır. Bu süre yalnızca sanal thread (virtual thread) üzerinde tam olarak uygulanır; gönderim bir platform thread'inde çalışıyorsa istek thread'ini uzun süre tutmamak için etkin bekleme 50 ms'e sınırlanır.
Varsayılan: 100 milisaniye
Üst Sınır: 2000 milisaniye
Yeniden Deneme
Açıklama: Başarısız bir çağrının en fazla kaç kez tekrar denenmesi
Varsayılan: 1
Açıklama: Denemeler arasındaki bekleme süresi
Varsayılan: 200 milisaniye
Açıklama: Sunucu 429/503 yanıtıyla birlikte Retry-After döndürdüğünde uygulanacak üst sınır
Varsayılan: 5 saniye
Açıklama: POST/PATCH gibi idempotent olmayan isteklerin de yeniden denenip denenmeyeceği
Varsayılan: Kapalı
POST/PATCH gibi istekler varsayılan olarak yeniden denenmez — bu, mükerrer kayıt oluşmasını önlemek içindir. GET/PUT/DELETE istekleri bir kez yeniden denenir. Idempotent Olmayan İsteklerde Yeniden Deneme açıldığında bu davranış değişir ve POST/PATCH istekleri de yeniden deneme kapsamına girer.
Splunk HEC Modu
Bu mod açıldığında kayıtlar Splunk HTTP Event Collector uç noktasının beklediği zarfa sarılarak /services/collector/event yoluna gönderilir; her bağlayıcı için sabit bir X-Splunk-Request-Channel kimliği kullanılır.
Açıklama: Kayıtların Splunk HEC zarfıyla gönderilip gönderilmeyeceği
Varsayılan: Kapalı
Açıklama: Splunk HEC zarfında taşınacak Index, Sourcetype, Source ve Host alanları
Varsayılan: Boş
Açıklama: Splunk'tan olay bazlı onay bekleyip beklenmeyeceği
Varsayılan: Kapalı
Açıklama: Onay bekleme süresi
Varsayılan: 30 saniye
Açıklama: Onayı gelmeyen toplu kaydın en fazla kaç kez yeniden gönderileceği
Varsayılan: 2
Onay kullanımı açıldığında Splunk'tan onay beklenir; onay belirtilen sürede gelmezse toplu kayıt sınırlı sayıda yeniden gönderilir, sınır aşıldığında kayıt tanımlıysa failover connector'a yönlendirilir; failover tanımlı değilse düşürülür.
Splunk HEC'in 200 yanıtı kaydın kuyruğa alındığı anlamına gelir, indekslendiği anlamına gelmez. Uzun süreli saklama taahhüdü olan kurulumların Onay (ACK) Kullanımı seçeneğini açması önerilir.
Kullanım Senaryoları
Durum: Gateway loglarını merkezi SIEM'e aktarma ihtiyacı
Çözüm: POST + JSON payload + Authorization header
Beklenen Sonuç: SIEM webhook'u her entegrasyon sonunda log kaydını alır
Durum: CI/CD pipeline sonrası ekipleri bilgilendirme
Çözüm: POST https://hooks.slack.com/... + ContentType: application/json
Beklenen Sonuç: Slack kanalında build/deployment sonucu paylaşılır
Durum: Threshold aşımlarında ITSM bileti açma
Çözüm: POST https://api.servicenow.com/... + API key
Beklenen Sonuç: ServiceNow üzerinde otomatik incident oluşur
Durum: CRM etkinliği tetiklemek
Çözüm: PUT https://crm.partner.com/events/id + Bearer token
Beklenen Sonuç: CRM kaydı güncellenir ve mutabakat akışı devam eder
Durum: Health-check verisini Datadog Webhook API'sına gönderme
Çözüm: POST https://api.datadoghq.com/api/v1/webhooks
Beklenen Sonuç: Datadog metrik panosunda custom event açılır
Durum: Her Integration Flow çalışmasını arşiv servisine bildirme
Çözüm: POST https://audit.internal/api/event + X-Trace-Id header
Beklenen Sonuç: Audit servisi çağrıyı kaydeder ve geri dönüş verir
Dayanıklılık (Resilience)
Webhook hedef adresi (sunucu) geçici olarak erişilemez hale geldiğinde gateway'in istek işlemeye devam edebilmesi için bu bağlantıya bir devre kesici (circuit breaker) tanımlanabilir. Devre kesici yalnızca bu bağlantı üzerinden gönderilen log kayıtlarını (trafik logu, token logu, denetim logu vb.) korur; API Proxy'nin backend'e ilettiği istekleri ve Integration Flow / Scheduled Job üzerinden yapılan gönderimleri etkilemez.
Bu bağlantı için devre kesiciyi açar/kapatır.
Varsayılan: Kapalı (OFF)
Devrenin açılması için hata penceresi içinde birikmesi gereken ardışık hata sayısı.
Varsayılan: 5
Aralık: 1 - 10.000
Devre açıldıktan sonra tek bir yeniden deneme yapılmadan önce beklenecek süre.
Varsayılan: 30 saniye
Aralık: 1 - 3.600 saniye
Bu üç alandan biri boş bırakılırsa, Yönetim → Sistem Ayarları → Loglama ve İzleme (Logging & Monitoring) → Connector Devre Kesici kategorisi altındaki kurulum genelindeki varsayılan değer kullanılır.
Hata eşiği aşıldığında devre açılır: bu bağlantı üzerinden yapılacak log gönderimleri hedefe hiç ulaşmadan, tanımlıysa failover bağlantısına yönlendirilir; failover tanımlı değilse sayaçla düşürülür (drop edilir). Bekleme penceresi dolduğunda tek bir deneme yapılır; deneme başarılı olursa devre kapanır, başarısız olursa devre yeniden açılır.
Bu alanlardaki değişiklikler, bu bağlantıyı kullanan API Proxy'ler yeniden deploy edildikten sonra geçerli olur.
Connection Yapılandırma
Yeni Webhook Entegrasyonu Oluşturma
Yapılandırma Adımları
- Sol menüden Connection → Webhook Entegrasyonu bölümüne gidin.
- Sağ üstteki [+ Create] butonuna tıklayın.
Enable Status (Aktif Durumu):
- Toggle ile aktif/pasif durumu ayarlayın. Yeni connection'lar varsayılan olarak aktiftir.
Name (İsim) - Zorunlu:
- Örnek:
Production_Webhook - Benzersiz isim girin, boşlukla başlamaz.
- Sistem otomatik kontrol eder. Yeşil tik: kullanılabilir. Kırmızı çarpı: mevcut isim.
Description (Açıklama):
- Örnek: "Prod log forwarding webhook'u"
- Maks. 1000 karakter.
- Connection'ın amacını açıklayın.
Sayfanın üst kısmındaki işlem butonları alanında, [<> Variable] butonunu kullanarak dinamik değer seçebilir, Global variable ifadeleri sayesinde connection parametrelerini sabit değer yerine değişken tabanlı yönetebilirsiniz. Detaylı bilgi için Dinamik Değişkenler sayfasını inceleyebilirsiniz.
- Dropdown menüden ortam seçin: Development, Test, veya Production.
- Her ortam için farklı connection parametreleri tanımlanabilir.
- HTTP Method listesinden GET/POST/PUT vb. seçin.
- Full URL alanına https:// ile başlayan tam uç noktayı girin.
- Gerekirse query parametreleri veya path değişkenleri için placeholder kullanın.
- Headers sekmesinde + ile yeni satır ekleyin.
- Header Name ve Header Value alanları boş bırakılamaz.
- Otomatik tamamlama listesinden yaygın başlıkları seçebilirsiniz.
- Settings sekmesindeki Timeout alanı isteğin tamamlanması için maksimum süreyi (saniye) belirler; Connect/Response/Connection Request/Socket Timeout alanları boş bırakılırsa bu değere düşer.
- Bağlantı Havuzu - Host Başına ve Bağlantı Havuzu - Toplam alanlarını gerekiyorsa aynı sekmede ayarlayın; boş bırakıldığında sırasıyla 24 ve 48 varsayılan değerleri kullanılır.
- API anahtarları veya Bearer token'ları Authorization başlığına yazın.
- Temel HTTP auth gerekiyorsa Authorization: Basic ... oluşturun.
- HTTPS URL'leriyle SSL/TLS koruması sağlanır; gerektiğinde mutual TLS için sertifika bağlantısını environment seviyesinde yapılandırın.
- [Test Connection] butonuna tıklayın.
- Bağlantı parametrelerinin doğru olup olmadığını test edin.
- Başarılı: Yeşil onay mesajı
- Başarısız: Hata detayları gösterilir
- Sağ üstteki [Save and Deploy] butonuna tıklayın.
Kontrol Listesi:
- Benzersiz isim
- Zorunlu alanlar dolu
- Test connection başarılı (önerilir)
Sonuç:
- Connection listeye eklenir
- Integration Flow ve Connector adımlarında kullanılabilir hale gelir
- Ortama göre aktif olur
Connection başarıyla oluşturuldu! Artık Integration Flow ve Connector adımlarında kullanabilirsiniz.
Connection'ı Silme
Connection'ı silmek için:
- Connection'ın view ekranına gidin.
- Sağ üstteki [Delete] butonuna tıklayın.
- Onay dialogunda silme işlemini onaylayın.
- Connection listesinde satır sonundaki ⋮ menüsünden Delete seçeneğini tıklayın.
- Onay dialogunda silme işlemini onaylayın.
Silmeden Önce Kontrol Edin:
- Integration Flow veya Connector adımlarında kullanılıyor olabilir.
- Gerekirse alternatif bir connection atayın.
- Silmeden önce Export ile yedek alın.
- Silmek yerine connection'ın aktif durumunu pasif hale getirin.
- Connection pasif olur ancak silinmez.
- Gerektiğinde aktif hale getirerek yeniden kullanabilirsiniz.
Connection'ı Dışa/İçe Aktarma
Bu adımda kullanıcı, mevcut connection'ları yedekleme, farklı ortamlara taşıma veya paylaşma amacıyla dışa aktarabilir (export) ya da daha önce dışa aktarılmış bir connection'ı tekrar içe aktarabilir (import). Bu işlem, sürüm yönetimi, test ve üretim ortamları arasında geçiş veya ekipler arası paylaşım süreçlerinde veri bütünlüğünü korumak için kullanılır.
Dışa Aktarma (Export)
- Connection'ın view ekranına gidin.
- Sağ üstteki [Export] butonuna tıklayın.
- ZIP dosyası otomatik olarak indirilir.
- Connection listesinde satır sonundaki ⋮ menüsünden Export seçeneğini tıklayın.
- ZIP dosyası otomatik olarak indirilir.
Format: {Date}-webhook-integration-{ConnectionName}-export.zip
Örnek: 13 Nov 2025-webhook-integration-Production_Webhook-export.zip
- Connection JSON dosyası
- Metadata bilgileri
- Bağımlılık bilgileri (örneğin sertifikalar, key store)
- Yedekleme
- Ortamlar arası taşıma (Test → Prod)
- Versiyonlama
- Ekip veya proje bazlı paylaşım
İçe Aktarma (Import)
- Ana listede [Import Webhook Entegrasyonu] butonuna tıklayın.
- İndirilen ZIP dosyasını seçin.
- Sistem kontrolleri: Format geçerli mi? İsim çakışması var mı? Bağımlılıklar mevcut mu?
- Ardından [Import] butonuna tıklayın.
Senaryo 1: İsim Çakışması → Eski connection'ın üzerine yazın veya yeni bir isimle oluşturun.
Senaryo 2: Eksik Bağımlılıklar → Eksik sertifikaları veya key store'ları önce oluşturun veya import sırasında çıkarın.
Connection'ın Kullanım Alanları
Adımlar:
- Connection'ı oluşturun
- Test Connection ile bağlantıyı doğrulayın
- Save and Deploy ile kaydedin ve etkinleştirin
- Connection'ın Enabled durumda olduğundan emin olun.
HTTP/REST tabanlı webhook çağrıları gerektiren adımlarda connection seçilir. Örnek: "Send Webhook", "Invoke REST API", "HTTP Request", "Log to External Endpoint" gibi adımlar. Bağlantı seçimi bu adımların yapılandırmasında yer alan Connection alanından yapılır.
Zamanlanmış görevlerde (ör. belirli aralıklarla webhook çağrısı, bildirim gönderme vb.) bağlantı seçilerek HTTP uç noktalarına erişim sağlanır. Connection değiştiğinde, job çalışma davranışı da buna göre güncellenir.
Connection Test özelliği ile bağlantının doğruluğu Integration Flow'dan bağımsız olarak kontrol edilebilir. Bu test hata ayıklama sürecinde kritik önem taşır.
Best Practices
Yapılması Gerekenler ve En İyi Uygulamalar
Kötü: Tüm çağrıları POST olarak göndermek
İyi: Hedef servisin gerektirdiği metodu seçmek
En İyi: CRUD operasyonları için GET/POST/PUT/PATCH/DELETE kullanımını sözleşmeye göre ayarlamak
Kötü: URL içinde sabit v1/v2 path'lerini manuel değiştirmek
İyi: Yeni connection oluşturarak farklı versiyonları ayırmak
En İyi: Parametrik URL tanımı kullanıp ortam bazlı olarak versiyonları yönetmek
Kötü: Authorization başlığını düz metin olarak paylaşmak
İyi: API anahtarlarını sadece ilgili connection'da saklamak
En İyi: Secret Manager üzerinden dinamik olarak çekilen token'ları kullanmak
Kötü: Test edilmemiş connection'ı Production'a deploy etmek
İyi: Test ortamında doğruladıktan sonra kopyalamak
En İyi: Export/Import ile versiyonlayıp değişiklik kaydını saklamak
Kötü: Tüm ortamlarda aynı connection parametrelerini kullanmak
İyi: Her ortam için ayrı connection oluşturmak
En İyi: Environment seçeneğini kullanarak tek connection'da tüm ortamları yönetmek, ortamlar arası geçişte sadece environment değiştirmek
Kötü: Connection'ı test etmeden kaydetmek ve deploy etmek
İyi: Kaydetmeden önce Test Connection ile doğrulamak
En İyi: Her parametre değişikliğinden sonra test etmek, production'a geçmeden önce test ortamında tam entegrasyon testi yapmak
Güvenlik En İyi Uygulamaları
API anahtarlarını aynı header'da hem Test hem Prod için kullanmayın. Her ortam için farklı anahtar tanımlayın ve rotasyon takvimi oluşturun
Konsol çıktılarında hassas header değerlerinin loglanmasını kapatın. Sadece anonimize edilmiş X-Trace-Id gibi bilgileri açık bırakın
Webhook uç noktasında IP whitelisting veya HMAC imza doğrulaması kullanın. Apinizer tarafında ilgili imza başlığını otomatik üretin
Kullanıcı adı ve şifre gibi hassas bilgileri environment variable veya secret manager kullanarak saklayın. Kimlik bilgilerini kod veya konfigürasyon dosyalarına hardcode etmeyin. Periyodik olarak şifreleri güncelleyin
Production ortamında mutlaka SSL/TLS aktif edin. Self-signed sertifikalar sadece development ortamında kullanın. Sertifika expiration tarihlerini takip edin ve zamanında yenileyin
Connection yapılandırmasını sadece yetkili kullanıcıların değiştirmesine izin verin. Connection değişiklik loglarını saklayın. Kritik connection'lar için değişiklik approval süreci uygulayın
Kaçınılması Gerekenler
Neden kaçınılmalı: Token sızıntısında tüm ortamlar etkilenir
Alternatif: Ortam bazlı farklı Authorization değerleri kullanın
Neden kaçınılmalı: Şifrelenmemiş kanalda veri tanır
Alternatif: URL'yi HTTPS yapın, gerekirse hedef tarafa sertifika sağlayın
Neden kaçınılmalı: Aynı başlık birden fazla kez gönderilerek hedef sistemde hata oluşur
Alternatif: Header tablosunu düzenli gözden geçirip gereksiz satırları kaldırın
Neden kaçınılmalı: Test verileri production sistemine yazılabilir, gerçek kullanıcılar etkilenebilir, güvenlik riski oluşur
Alternatif: Her ortam için ayrı connection oluşturun, environment parametresini kullanın, connection isimlerini ortama göre prefix ekleyerek ayırın (Test_, Prod_)
Neden kaçınılmalı: Ağ gecikmelerinde connection sürekli timeout olur, Entegrasyon adımları başarısız olur
Alternatif: Gerçek kullanım senaryolarına göre timeout değerlerini ayarlayın, network latency'yi ölçün ve timeout'ları buna göre belirleyin
Neden kaçınılmalı: Bağlantı havuzu (Host Başına / Toplam) her zaman etkindir; varsayılan değerler (24 / 48) yüksek eşzamanlı trafikte yetersiz kalabilir, istekler havuzdan boş bağlantı beklerken timeout alabilir
Alternatif: Host Başına ve Toplam bağlantı sayısını gerçek eşzamanlı istek hacmine göre ayarlayın; Toplam'ın Host Başına'nın altında kalması engellenmez ama çalışma zamanında otomatik yukarı çekilir ve WARN olarak loglanır
Performans İpuçları
Öneri: Webhook mesajlarını 200 KB altında tutun
Etki: Daha kısa yanıt süreleri ve daha düşük timeout oranı
Öneri: Yüksek hacimli tetikleyicilerde Integration Flow tarafında concurrency sınırlarını tanımlayın
Etki: Hedef sistem aşırı yüklenmez, hata oranı düşer
Öneri: Idempotent uç noktalar için Flow'da retry politikası ekleyin, non-idempotent çağrılarda hatayı loglayıp manuel aksiyon alın
Etki: Kritik işlemlerde veri kaybı önlenir
Öneri: Host Başına ve Toplam bağlantı sayısını gerçek eşzamanlı istek hacmine göre ayarlayın; Toplam değerini Host Başına değerinin altına düşürmeyin (düşerse çalışma zamanında otomatik yukarı çekilir ve WARN loglanır)
Etki: Bağlantı açma maliyeti azalır, havuzdan bağlantı bekleme (Bağlantı İsteği Süresi) riski düşer
Öneri: Gerçek network latency'yi ölçün, timeout değerlerini buna göre ayarlayın, çok düşük veya çok yüksek timeout'lardan kaçının
Etki: Gereksiz beklemeler önlenir, h ızlı fail-over sağlanır, kullanıcı deneyimi iyileşir
Öneri: Connection pool kullanımını izleyin, timeout oranlarını takip edin, connection health check yapın, alerting kurun
Etki: Sorunlar proaktif tespit edilir, performans darboğazları erken belirlenir, kesinti süresi azalır
Sorun Giderme (Troubleshooting)
Webhook 4xx Hatası
Yanlış endpoint, eksik header veya hatalı payload format olabilir.
URL ve HTTP metodunu doğrulayın.
Zorunlu header'ların gönderildiğini kontrol edin.
Hedef dokümantasyona göre payload'ı yeniden formatlayın.
Test Connection Başarısız ve 5xx Döndü
Hedef servis kapalı, TLS sertifikası reddedildi veya rate limit alınmış olabilir.
Hedef servisin sağlığını kontrol edin.
HTTPS sertifika zincirini doğrulayın.
Rate limit loglarını inceleyip bekleme süresi ekleyin.
Connection Timeout
Network gecikmesi, hedef sistem yavaş yanıt veriyor veya timeout değeri çok düşük olabilir.
Network connectivity kontrol edin.
Hedef sistem sağlığını kontrol edin.
Timeout değerlerini artırın.
Connection loglarını inceleyin.
Authentication Failed
Yanlış kullanıcı adı/şifre, expired credentials veya yetki problemi olabilir.
Kimlik bilgilerini doğrulayın.
Hedef sistemde kullanıcının aktif olduğunu kontrol edin.
Gerekli yetkilerin verildiğini kontrol edin.
SSL/TLS sertifikalarını kontrol edin.
Bağlantı Havuzu Tükendi (Pool Exhausted)
Host Başına veya Toplam bağlantı sayısı trafiğe göre düşük kalmış, bağlantılar düzgün serbest bırakılmıyor ya da hedef sistem yavaş yanıt veriyor olabilir.
Host Başına ve Toplam bağlantı sayısını gerçek eşzamanlı istek hacmine göre yükseltin.
connectionRequestTimeoutSeconds değerinin çok düşük olup olmadığını kontrol edin; havuzdan bağlantı alma bu süre içinde tamamlanamazsa istek başarısız olur.
Hedef servis yavaş yanıt veriyorsa bağlantılar uzun süre meşgul kalır ve havuz daha çabuk dolar.
Toplam değeri Host Başına değerinin altındaysa çalışma zamanında otomatik yukarı çekilir; bu durum bir WARN log satırı üretir, logları bu uyarı için kontrol edin.
Connection Test Başarılı Ama Entegrasyon Akışı Hata Veriyor
Integration/Connector adımında farklı connection seçili olabilir, adım yanlış yapılandırılmış olabilir veya Flow/Job redeploy edilmemiş olabilir.
Connection'ın enable toggle'ının aktif olduğunu kontrol edin.
Integration Flow'da doğru connection'ın seçildiğini doğrulayın.
Connection'ı tekrar deploy edin.
Integration Flow veya Job'ı redeploy edin.
Gateway loglarını kontrol edin.
Sık Sorulan Sorular (SSS)
Aynı webhook connection'ı hem Slack hem de Teams için kullanabilir miyim?
Aynı connection tek bir URL'ye yönlenir. Farklı platformlar için farklı connection oluşturmanız veya URL'yi parametrik hale getirmeniz gerekir.
Name alanı neden kaydetmeden önce hata veriyor?
Listede aynı isimde connection varsa servis nameExist=true döner ve kaydetmeye izin vermez. İsmi benzersiz olacak şekilde güncelleyin.
Header tablosuna kaç adet satır ekleyebilirim?
Sınırlama yoktur ancak her satırın name ve value değerleri dolu olmalıdır; aksi halde kaydetme engellenir.
Timeout alanı hangi birimde çalışıyor?
UI saniye cinsinden değer alır ve backend bu değeri milisaniyeye çevirerek HTTP istemcisine aktarır.
Test Connection hangi ortamda çalışır?
Seçtiğiniz environment kimliğine göre Publication Worker üzerinde çalışır ve gerçek endpoint'e ulaşmaya çalışır.
Aynı connection'ı birden fazla Integration Flow'da kullanabilir miyim?
Evet, aynı connection birden fazla Integration Flow veya Connector adımında kullanılabilir. Bu merkezi yönetim sağlar ve konfigürasyon tutarlılığını garanti eder. Ancak connection'da yapılan değişiklikler tüm kullanım yerlerini etkileyeceği için dikkatli olunmalıdır.
Bağlantı havuzunu kapatabilir miyim?
Hayır. Bağlantı havuzu her zaman etkindir, bir aç/kapa anahtarı yoktur. Yapılandırılabilen tek şey Host Başına ve Toplam bağlantı sayısı üst sınırlarıdır.
Test ve Production için farklı connection'lar mı oluşturmalıyım?
Evet, her ortam için ayrı connection oluşturmanız önerilir. Alternatif olarak environment parametresini kullanarak tek connection içinde tüm ortamları yönetebilirsiniz. Bu yaklaşım daha kolay yönetim ve daha az hata riski sağlar.
Test Connection başarılı ama Integration Flow'da çalışmıyor, neden?
Birkaç neden olabilir:
- Connection enable toggle'ı pasif olabilir
- Integration adımında farklı bir connection seçili olabilir
- Connection deploy edilmemiş olabilir
- Integration Flow henüz redeploy edilmemiş olabilir