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
HTTP istemcisi keep-alive destekli tekil bağlantıları kısa süreliğine reuse eder; açık bağlantı yoksa yeni bir TCP oturumu kurulur
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.
İ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ığı, pool durumu 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
Açıklama: TCP bağlantısının kurulması için bekleme süresi
Varsayılan: 2000
Min: 1000 | Max: 60000
Birim: milisaniye
Açıklama: HTTP isteğinin toplam yanıt süresi
Varsayılan: 2000
Min: 1000 | Max: 60000
Birim: milisaniye
Açıklama: Connection pool'daki maksimum bağlantı sayısı
Varsayılan: 0
Min: 0 | Max: 0
Birim: adet
Açıklama: Tekrar denemeler arasındaki bekleme (manuel akışlarla kullanılabilir)
Varsayılan: -
Birim: saniye
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
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.
- Pool size sunucu tarafından yönetildiği için UI üzerinde sadece timeout değeri değiştirilir.
- 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 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 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ı: Her istekte yeni bağlantı açılır, performans düşer, kaynak tüketimi artar, hedef sistem yükü artar
Alternatif: Connection pool aktif edin, pool size'ı trafik hacmine göre ayarlayın, pool monitoring kurun
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: Pool size'ı peak trafiğe göre ayarlayın (önerilen: eşzamanlı istek sayısı × 1.5), idle connection timeout'ları belirleyin, pool health check yapın
Etki: Bağlantı açma maliyeti %80 azalır, yanıt süreleri düşer, kaynak kullanımı optimize edilir
Ö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.
Pool Exhausted
Pool size çok düşük, connection leak var veya trafik çok yüksek olabilir.
Pool size'ı artırın.
Connection'ların düzgün kapatıldığını kontrol edin.
Idle connection timeout'ları ayarlayın.
Connection kullanım metriklerini izleyin.
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.
Connection pool kullanmak zorunlu mudur?
Connection pool kullanımı zorunlu değildir ancak yüksek trafikli sistemlerde şiddetle önerilir. Her istekte yeni bağlantı açmak yerine mevcut bağlantıları yeniden kullanmak performansı önemli ölçüde artırı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