Webhooks

Selwise'ın topladığı olayları, siz bir uç nokta tanımladığınız anda kendi sisteminize HTTP POST isteğiyle gönderir. Bu sayfa panel ekranını ve kurulum akışını anlatır; isteğin gövdesi, imza doğrulama kodu ve tekilleştirme için bkz. Webhook Payload ve İmza.

Panelde nerede

Sol menüde Ayarlar → Entegrasyonlar (Settings → Integrations). Sayfadaki Webhooks bölümünde Manage Webhooks (Webhook'ları Yönet) bağlantısı listeye götürür. Doğrudan adres: /dashboard/integrations/webhooks; yeni kayıt için Create Webhook (Webhook Oluştur) düğmesi /dashboard/integrations/webhooks/new, düzenleme /dashboard/integrations/webhooks/<id> adresindedir.

Webhook'lar kanala aittir: üstteki kanal seçicide hangi kanal seçiliyse onun olayları gider. Kanal seçili değilse ekran "Please select a site first" (Önce bir site seçin) der.

Tek dışa aktarım yolu

Selwise'tan dışarıya veri yalnızca webhook ile çıkar; olayları bir reklam ya da analitik platformuna kendisi aktarmaz. Böyle bir hedefe veri göndermeniz gerekiyorsa webhook'u kendi sisteminize bağlayın ve aktarımı oradan yapın. Ters yön, sitenizin mevcut dataLayer verisinden Selwise'ı beslemek, ayrı bir konudur: Veri Katmanı.

Ne için kullanılır

Amaç	Örnek
Bülten ve kullanıcı olaylarını kendi sisteminize taşımak	user_signup olayını CRM'e yazmak
Kendi veri ambarınıza olay akıtmak	Seçtiğiniz olayları kendi API'nize göndermek
İç sistemleri tetiklemek	purchase olayında stok veya lojistik servisini çağırmak

Selwise e-posta göndermez, adres toplamaz; webhook yalnızca olayı sizin uç noktanıza iletir.

Liste ekranı

Her webhook bir kart olarak görünür: ad, adres, kimlik doğrulama rozeti, seçili olay sayısı (Events (Event)), Delivered (Teslim), Failed (Başarısız) ve Last Status (Son Durum). Kartın altında Test (Test Et), Logs (Loglar), Edit (Düzenle) ve silme düğmeleri vardır. Webhook Active değilse Test düğmesi gridir.

Delivered ve Failed olay sayar, deneme değil: bir olay ilk denemede ya da bir yeniden denemede 2xx alırsa bir kez Delivered, bütün denemeler tükenirse bir kez Failed sayılır. Hâlâ yeniden denenen bir olay ikisinde de görünmez.

Webhook tanımlama

Alan	Açıklama
Name (Ad)	Panelde görünen ad, en fazla 255 karakter
Endpoint URL	http:// veya https:// ile başlayan, herkese açık adres
Active (Aktif)	Kapalıyken hiçbir olay gönderilmez ve test yapılamaz
Events to Send (Gönderilecek Event'ler)	En az bir olay seçilir; webhook yalnızca seçilenleri alır
Authentication (Kimlik Doğrulama)	Aşağıda
Sign deliveries (Gönderimleri imzala)	Aşağıda; kimlik doğrulamadan bağımsız bir anahtar
Custom headers (Özel başlıklar)	Aşağıda
Retry Policy (Yeniden Deneme Politikası)	Aşağıda

Adres kuralları

Adres sunucudan çağrıldığı için şu adresler reddedilir (400): localhost, özel ağ ve loopback adresleri (10.x, 172.16-31.x, 192.168.x, 127.x, 169.254.x), adı bu adreslere çözülen alan adları, adreste kullanici:sifre@ biçiminde kimlik bilgisi ve veritabanı ile posta gibi ayrılmış portlar (22, 25, 465, 587, 3306, 5432, 6379, 27017 gibi). Yerelde geliştirme için tünel kullanın.

Adres her gönderimde yeniden kontrol edilir (kaydedildikten sonra alan adı başka bir adrese yönlendirilmiş olabilir) ve gönderim, kontrol edilen adrese yapılır. Yönlendirme izlenmez: uç noktanız 301, 302 ya da başka bir 3xx dönerse teslimat başarısız sayılır. Adresi son hâliyle girin; örneğin http:// yerine https://, eski alan adı yerine yenisi.

Olay seçimi

Liste, Selwise'ın bütün olay adlarını gösterir (52 ad; kategorileri ve ne zaman üretildikleri Event Referansı sayfasındadır). Her seçili olay için bir HTTP isteği gider; toplu gönderim yoktur. impression, scroll, hover veya product_impression gibi yüksek hacimli olayları yalnızca gerçekten işleyecekseniz seçin.

Olay adı, sunucunun normalize ettiği kanonik addır: tanınmayan bir ad custom_event olarak gelir.

Kimlik doğrulama

Seçenek	Alanlar	Gönderilen
No Auth (Yetkilendirme Yok)	yok	Doğrulama yok; açık uçlu bir adreste kullanmayın
Bearer Token	Bearer Token	Authorization: Bearer <token>
Basic Auth	Username, Password	Authorization: Basic <base64>
API Key	Header Name (varsayılan X-API-Key), API Key Value	Seçtiğiniz başlıkta anahtar

Seçilen türün gizli alanı zorunludur: token'ı boş bir Bearer Token hiç Authorization başlığı göndermezdi, form bunu artık kaydetmez.

Gizli değerler kayıttan sonra geri okunamaz; ekranda •••• ile görünür ve veritabanında şifrelenmiş saklanır. Değeri korumak için kutuya dokunmayın; değiştirmek için yenisini yazın. Başka bir alanı değiştirmek (ör. kullanıcı adını) kayıtlı gizli değeri korur.

İmza

Sign deliveries (Gönderimleri imzala) açıkken her gönderim, gövdenin HMAC-SHA256 imzasını Signature Secret ile hesaplanmış olarak Header Name başlığında (varsayılan X-Signature) taşır. İmza kimlik doğrulamanın bir türü değil, onun yanındadır: Bearer Token, Basic Auth veya API Key ile birlikte açılabilir. Gönderenin Selwise olduğunu ve gövdenin yolda değişmediğini kanıtlayan tek ayar budur; açık tutmanızı öneririz. Doğrulama kodu: Webhook Payload ve İmza.

Eskiden kimlik doğrulama türü olarak HMAC Signature seçilmiş webhook'lar formda "No Auth + imza açık" olarak görünür ve aynı şekilde imzalanmaya devam eder.

Özel başlıklar

Custom headers (Özel başlıklar) her gönderime eklenecek ek ad: değer çiftleridir; uç noktanız bir kiracı kimliği, yönlendirme anahtarı ya da ikinci bir kimlik bilgisi bekliyorsa buraya yazın. Add header (Başlık ekle) ile satır ekleyin.

Kural	Neden
En fazla 20 başlık; ad en fazla 100, değer en fazla 2000 karakter	Sunucunun kabul ettiği sınırlar
Ad yalnızca harf, rakam ve - gibi başlık karakterlerinden oluşur; boşluk ve : olmaz	Geçersiz bir adla HTTP isteği hiç gönderilemez
Değer satır sonu içeremez	Başlık enjeksiyonunu önler
Content-Type, Content-Length, Host, User-Agent, Authorization, X-Selwise-Delivery-Id, X-Selwise-Event kullanılamaz	Bunları Selwise her gönderimde kendisi ekler; Authorization için kimlik doğrulama ayarını kullanın
API anahtarının ve imzanın gönderildiği başlık adı kullanılamaz	Aynı ad iki kez gönderilemez
Aynı ad iki kez yazılamaz (büyük/küçük harf fark etmez)	x-tenant ile X-Tenant aynı başlıktır

Secret (Gizli) işaretli bir başlığın değeri şifrelenmiş saklanır ve kayıttan sonra •••• olarak görünür; kimlik doğrulama sırlarıyla aynı kural geçerlidir: dokunmazsanız korunur, yenisini yazarsanız değişir. Gizli bir başlığın adını değiştirir ya da Secret işaretini kaldırırsanız değeri yeniden girmeniz gerekir, çünkü kayıtlı değer başlığın eski hâline aittir. Gizli olmayan değerler panelde açık görünür; parola veya token taşıyan bir değeri gizli olarak işaretleyin.

Yeniden deneme

Alan	Aralık	Varsayılan
Max Attempts (Maks. Deneme)	1 – 10	3
Initial Delay (ms) (İlk Gecikme)	1000 – 300000	60000
Backoff Multiplier (Backoff Çarpanı)	1 – 5, tam sayı	2

Bir istek zaman aşımına uğrarsa (varsayılan 30 saniye), bağlantı kurulamazsa, 5xx veya 429 yanıtı alırsa yeniden denenir. Diğer 4xx yanıtlar (400, 401, 404…) yeniden denenmez; bunlar sizin tarafınızdaki bir yapılandırma hatasıdır.

Max Attempts, ilk denemeden sonraki yeniden deneme sayısıdır: varsayılanlarla bir olay en fazla dört kez gönderilir. Yeniden denemeler arasındaki bekleme:

Deneme	Ne zaman (varsayılanlarla)
1. deneme	Olay geldikten hemen sonra, kuyruktan
1. yeniden deneme	İlk hatadan 60 sn sonra
2. yeniden deneme	Öncekinden 120 sn sonra
3. yeniden deneme	Öncekinden 240 sn sonra

Genel kural: n. yeniden deneme Initial Delay × Backoff Multiplier^(n-1) bekler. Bir 4xx yanıtı (429 hariç) uç noktanızın reddidir; ne ilk denemede ne bir yeniden denemede tekrar gönderilmez. Yeniden denemeler aynı gövdeyi ve aynı imzayı taşır.

Teslimat logları

Kartta Logs (Loglar) son 50 kaydı açar. Her kayıtta olay adı, durum (success, failed, retrying), yeniden deneme sayısı (Retry n), bir sonraki deneme zamanı (Next retry at), hata (Error), uç noktanızın yanıtının ilk 1000 karakteri (Response) ve gönderilen gövde (Event Data) vardır.

Her olay log'da tek satırdır ve denemeler ilerledikçe aynı satır güncellenir: pending (sırada, henüz gönderilmedi) → success, ya da retrying (bir sonraki deneme bekleniyor) → success / failed. Log'lar ödeme ve kişisel veri içerebilen gövdeyi aynen saklar; ekranı paylaşırken dikkat edin.

Adres ve tünel ile test

1. Yerelde bir alıcı çalıştırın (örnek kod burada) ve bir tünel açın: ngrok http 3000 veya cloudflared tunnel --url http://localhost:3000. Hızlı gözlem için webhook.site de yeterlidir.
2. Tünelin https:// adresini Endpoint URL olarak girin, kimlik doğrulamayı seçin, Active açık kalsın ve kaydedin.
3. Kartta Test'e basın. Uç noktanıza event: "test_event" olan bir istek gider ve sonuç ekranda görünür; olay seçiminden bağımsızdır.
4. Logs'ta isteğin, yanıt kodunuzun ve imzanın doğru olduğunu görün.
5. Gerçek olay için kendi sitenizde bir sayfayı gezin; seçtiğiniz olay saniyeler içinde gelir.

Test isteği de başarısız olursa kuralları aynen izler ve yeniden denenir.

Tipik akış

1. Alıcınızı yazın: imzayı doğrulasın, hemen 200 dönsün, işi kuyruğa alsın.
2. Webhook'u tanımlayın, Test ile doğrulayın.
3. Yalnızca ihtiyacınız olan olayları seçin.
4. İlk gerçek olaylardan sonra Logs'ta success satırlarını ve Failed sayacını izleyin.

Neden boş, neden gri

Belirti	Neden
Ekran menüde yok	Hesabınızda Integrations modülü satın alınmamış; hesap yöneticinize başvurun
Create Webhook hata veriyor	Planınızdaki webhook sayısı sınırına ulaşıldı
Test gri	Webhook Active değil
Hiç olay gelmiyor	Webhook pasif; seçtiğiniz olay üretilmiyor; ziyaretçi çerez onayı vermediği için olay hiç alınmadı (bkz. Onay Yönetimi); ya da kanal seçili değil
Yalnızca 401 görüyorum	Alıcınız gizli değeri/başlığı reddediyor; 4xx yeniden denenmez, düzeltip yeni olay bekleyin
Aynı olay iki kez geliyor	Yeniden deneme veya iki kaynak; eventId ile tekilleştirin (ayrıntı)
Kayıt 400 ile reddedildi	Adres özel ağa çözülüyor, ayrılmış port kullanıyor veya olay adı geçersiz