> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apinizer.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Webhook
> HTTP tabanlı webhook uç noktalarına tek connection ile güvenli çağrı gönderimi yapar. HTTP/REST üzerinden dış servislere güvenli veri gönderimi ve bildirim gerçekleştirebilir
## Genel Bakış
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
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
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
EnumHttpRequestMethod listesindeki GET/POST/PUT/DELETE vb. tüm metotlar tek dropdown üzerinden seçilir.
Tam URL (fullUrl) alanı ile [https://host/path](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.
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
**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
**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/](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/](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](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](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](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](/tr/concepts/temel-kavramlar/dinamik-degiskenler) 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.
* 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
* 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:**
1. Connection'ı oluşturun
2. Test Connection ile bağlantıyı doğrulayın
3. Save and Deploy ile kaydedin ve etkinleştirin
4. 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
**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
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
**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
**Ö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)
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.
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.
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.
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 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.
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ı connection tek bir URL'ye yönlenir. Farklı platformlar için farklı connection oluşturmanız veya URL'yi parametrik hale getirmeniz gerekir.
Listede aynı isimde connection varsa servis nameExist=true döner ve kaydetmeye izin vermez. İsmi benzersiz olacak şekilde güncelleyin.
Sınırlama yoktur ancak her satırın name ve value değerleri dolu olmalıdır; aksi halde kaydetme engellenir.
UI saniye cinsinden değer alır ve backend bu değeri milisaniyeye çevirerek HTTP istemcisine aktarır.
Seçtiğiniz environment kimliğine göre Publication Worker üzerinde çalışır ve gerçek endpoint'e ulaşmaya çalışır.
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 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.
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.
Birkaç neden olabilir:
1. Connection enable toggle'ı pasif olabilir
2. Integration adımında farklı bir connection seçili olabilir
3. Connection deploy edilmemiş olabilir
4. Integration Flow henüz redeploy edilmemiş olabilir