Giriş

İki hizmet arasında bir entegrasyon kurduysanız — örneğin bir sistemdeki verilerin otomatik olarak bir CRM'e veya Google E-Tablolar'a aktarılması için — muhtemelen "webhook" terimiyle karşılaşmışsınızdır. Bu, Slack bildirimlerinden bir çevrimiçi mağazadaki sipariş senkronizasyonuna kadar, modern otomasyonun büyük bir kısmını sessizce destekleyen teknolojilerden biridir. Bu yazıda, webhook'un basit bir şekilde ne olduğunu, sıradan API isteklerinden nasıl farklı olduğunu ve Lix.li'deki webhook'ları kullanarak kısa linkler için tıklama bildirimlerinin pratikte nasıl kurulacağını ele alacağız.

Webhook Nedir, Basitçe Anlatalım

Bir webhook, belirli bir olay gerçekleştiği anda bir hizmetten diğerine otomatik olarak veri aktarma yöntemidir. Sisteminiz sürekli "yeni bir şey var mı?" diye sormak yerine, olay gerçekleştiği anda hizmet, verileri kendisi sunucunuza gönderir. Aradaki farkı anlamanın en kolay yolu bir posta benzetmesidir:

Sıradan bir API isteği, bir mektubun gelip gelmediğini kontrol etmek için tekrar tekrar posta kutusuna kendinizin gitmesi gibidir.
Bir webhook ise bir teslimat hizmetine kaydolmak gibidir: mektup hazır olur olmaz kendiliğinden kapınıza gelir. Teknik olarak bir webhook, ilgili olay gerçekleştiğinde — bir sipariş ödemesi, bir görev durumu değişikliği veya Lix.li örneğinde olduğu gibi kısa bir linke tıklanması — bir sunucunun başka bir sunucudaki önceden yapılandırılmış bir URL'ye gönderdiği sıradan bir HTTP isteğidir (genellikle POST).

Webhook'lar Neden Önemli

Webhook'lar çok özel bir sorunu çözer: harici bir hizmeti sürekli sorgulamadan (polling) güncel verileri nasıl elde edersiniz? Webhook'lar olmadan, yeni olaylardan haberdar olmak için API'ye düzenli olarak istek göndermeniz gerekirdi — her dakika, her beş dakikada bir — ve her seferinde yeni bir şey olup olmadığını kontrol etmeniz gerekirdi. Bu, her iki sunucuya da gereksiz bir yük bindirir ve olayın gerçekleşmesi ile bundan haberdar olmanız arasına her zaman bir gecikme ekler. Webhook'lar bu mantığı tersine çevirir: bir şey gerçekleştiğinde hizmet size bildirir. Bu özellikle şunlar için kullanışlıdır:

İş süreçlerini otomatikleştirmek — örneğin, yeni potansiyel müşterileri otomatik olarak bir CRM'e kaydetmek.
Analitik entegrasyonları — tıklama verilerini kendi izleme sisteminize aktarmak.
Botlar ve bildirimler — olayları bir Telegram botuna veya ekibin Slack kanalına göndermek.
Veri senkronizasyonu — Google E-Tablolar'ı, panoları veya dahili sistemleri gerçek zamanlı olarak güncellemek.

Webhook'lar Nasıl Çalışır: Lix.li Örneği

Lix.li'de webhook'lar, kısa linklerinize yapılan tıklamalarla ilgili verileri doğrudan kendi sunucunuza almanızı sağlar — hizmetin API'sini sürekli sorgulamak zorunda kalmadan, otomatik olarak. Bu olayları CRM'inize, bir analitik sistemine, Google E-Tablolar'a, bir Telegram botuna veya başka herhangi bir otomasyon sistemine aktarmak istiyorsanız kullanışlıdır.

Nasıl Kurgulanmıştır

Tıklamalar tek tek gönderilmez — birkaç dakikada bir toplanır ve toplu halde teslim edilir. Bu, hem sizin sunucunuzun hem de Lix.li'nin sunucusunun yükünü azaltır.
Teslimat gerçek zamana yakın gerçekleşir, ancak anlık değildir — webhook'lar, her bir tıklamaya anında tepki vermek için değil, birkaç dakikalık bir gecikmenin kabul edilebilir olduğu senaryolar için tasarlanmıştır.
Teslimat, "en az bir kez" ilkesine göre garanti edilir: gönderim sırasında bir ağ hatası oluşursa, bir toplu iş tekrar gelebilir. Bu nedenle her olayın benzersiz bir event_id'si vardır — kendi tarafınızda kopyaları filtrelemek için bunu kullanmalısınız.

Panelde Bir Webhook Kurma

Webhook özelliği Premium pakette kullanılabilir. Kurulum sadece birkaç adımdan oluşur:

Panelinizde "Webhook'lar" bölümünü açın ve **"Ekle"**ye tıklayın.
Şunları belirtin:
- alıcı URL'si — gelen istekleri kabul edecek sunucunuzdaki adres (örneğin https://api.siteniz.com/webhooks/lix);
- kapsam — olayların tüm linkler için mi, belirli bir link grubu için mi, yoksa yalnızca tek bir link için mi gönderileceği;
- ziyaretçinin IP adresinin olay verilerine dahil edilip edilmeyeceği (kişisel veri olduğu için varsayılan olarak kapalıdır).
Webhook'u oluşturduktan hemen sonra, yalnızca bir kez görüntülenen bir gizli anahtar gösterilir — gelen isteklerin doğruluğunu kontrol etmek için kullanıldığından bunu kaydetmeyi unutmayın.
**"Test Et"**e tıklayın — hizmet bir test olayı gönderecek ve sunucunuzun doğru yanıt verip vermediğini gösterecektir.

Sunucunuza Ne Gelir

Her istek, application/json biçiminde bir gövdeyle POST yöntemi kullanılarak gönderilir. Verinin kendisiyle birlikte, istek birkaç hizmet başlığı da içerir:

Başlık	Amaç
`X-Lix-Signature`	`sha256=` biçiminde gövdenin imzası — doğrulama için kullanılır.
`X-Lix-Timestamp`	İsteğin gönderildiği zaman, bir Unix zaman damgası olarak.
`X-Lix-Delivery`	Benzersiz bir teslimat tanımlayıcısı.
`User-Agent`	`Lix-Webhooks/1.0` olarak ayarlanır.
İstek gövdesi, olayların toplu işini içerir:

{
  "delivery_id": "0f3b9c2e-6a1d-4e88-9d5a-2f8c1b7a4e10",
  "event_type": "redirects.batch",
  "sent_at": "2026-06-01T12:05:00Z",
  "window": {
    "from": "2026-06-01T12:00:00Z",
    "to":   "2026-06-01T12:03:30Z"
  },
  "count": 2,
  "truncated": false,
  "events": [
    {
      "event_id":   "2ef7bde608ce5404e97d5f042f95f89f1c232871",
      "link_id":    12345,
      "datetime":   "2026-06-01T12:01:00Z",
      "country":    "US",
      "city":       "Boston",
      "browser":    "Chrome",
      "os":         "Windows",
      "device":     "Desktop",
      "ref_domain": "google.com",
      "group_id":   null,
      "is_bot":     false
    }
  ]
}

Toplu işteki her olay, link kimliğini, UTC olarak tıklama zamanını, ülkeyi, şehri, tarayıcıyı, işletim sistemini, cihaz türünü, tıklamanın geldiği alan adını, grup kimliğini (belirlenmişse) ve bir bot olup olmadığını gösteren bir işareti içerir. Ziyaretçinin IP adresi, yalnızca webhook'u kurarken bu seçeneği açıkça etkinleştirdiyseniz veriye dahil edilir. Çok fazla olay birikmişse, bir toplu iş truncated: true olarak işaretlenebilir — bu, verinin bir kısmının bir sonraki teslimatla geleceği ve hiçbir şeyin kaybolmadığı anlamına gelir.

Bir İsteğin Doğruluğu Nasıl Doğrulanır

Sunucunuzun URL'si teknik olarak herhangi bir yerden bir istek alabildiğinden, bir isteğin gerçekten Lix.li'den geldiğini ve sahte olmadığını doğrulamak önemlidir. X-Lix-Signature başlığındaki imza tam olarak bunun içindir. Doğrulama prensibi şudur: isteğin "ham" (işlenmemiş) gövdesini alır, gizli anahtarınızı kullanarak bunun bir HMAC-SHA256 özetini hesaplar ve sonucu başlıkta gelenle karşılaştırırsınız. Zamanlama saldırılarını önlemek için karşılaştırma güvenli bir şekilde (sabit zamanlı) yapılmalıdır. PHP örneği:

$raw    = file_get_contents('php://input');
$secret = 'your_secret';
$expected = 'sha256=' . hash_hmac('sha256', $raw, $secret);
if (!hash_equals($expected, $_SERVER['HTTP_X_LIX_SIGNATURE'] ?? '')) {
    http_response_code(401);
    exit;
}

Node.js (Express) örneği:

const crypto = require('crypto');
// HAM gövdeyi almak önemlidir: app.use(express.raw({ type: 'application/json' }))
const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(req.body).digest('hex');
const got = req.header('X-Lix-Signature') || '';
if (expected.length !== got.length ||
    !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(got))) {
  return res.sendStatus(401);
}

Python (Flask) örneği:

import hmac, hashlib
raw = request.get_data()  # ham bayt'lar
expected = 'sha256=' + hmac.new(secret.encode(), raw, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, request.headers.get('X-Lix-Signature', '')):
    return '', 401

Alıcı Sunucunuz İçin Gereksinimler

Webhook'ların güvenilir bir şekilde çalışması için sunucunuzun birkaç kurala uyması gerekir:

Bir 2xx koduyla yanıt verin. Başka herhangi bir kod veya zaman aşımı başarısızlık olarak kabul edilir ve teslimat yeniden denenir.
Hızlı yanıt verin. Yanıt vermek için yalnızca birkaç saniyeniz var — verileri istek işleyicisinin içinde eşzamanlı olarak işlemekten kaçının. Doğru yaklaşım şudur: gelen verileri hızlıca kaydedin (örneğin bir kuyruğa veya veritabanına), 2xx döndürün ve ağır işlemi daha sonra ayrı olarak yapın.
event_id'ye göre tekrarları giderin. Yeniden deneme mekanizması nedeniyle, aynı olay bazen iki kez gelebilir.
İdempotent olun. Aynı toplu işi tekrar işlemek verilerinizi bozmamalıdır.
Her gelen istekte imzayı her zaman doğrulayın.
HTTPS kullanın. Webhook almak için yerel ve dahili adresler desteklenmez.

Hatalar Oluştuğunda Ne Olur

Sunucunuz bir 2xx koduyla yanıt vermezse, Lix.li denemeler arasındaki bekleme süresini kademeli olarak artırarak teslimatı yeniden dener. Alıcı uzun bir süre boyunca hiç yanıt vermezse (art arda birçok başarısız deneme), boşluğa veri göndermemek için webhook otomatik olarak duraklatılır. Bu, panelinizdeki teslimat günlüğünde gösterilir ve kendi tarafınızdaki sorunu düzelttikten sonra webhook'u tekrar açabilirsiniz.

Panelde Webhook Yönetimi

Yapılandırılmış her webhook için aşağıdaki işlemler kullanılabilir:

Test Et — tek bir test olayı gönderin ve sonucu hemen görün: başarı veya sunucunuzun belirli yanıt kodu.
Duraklat / Devam Et — olayların teslimatını geçici olarak durdurun veya devam ettirin.
Gizli anahtarı değiştirin — eskisinin yerine yeni bir anahtar oluşturun; eski anahtar anında çalışmayı durdurur, bu yüzden kendi tarafınızda da hemen güncellediğinizden emin olun.
Sil — webhook'u tamamen kaldırın.
Teslimat günlüğü — durumu, HTTP yanıt kodunu, toplu işteki olay sayısını ve gönderim zamanını gösteren son teslimatların geçmişi.

Sıkça Sorulan Sorular

Olaylar ne kadar hızlı gelir? Toplu olarak, yaklaşık birkaç dakikada bir, küçük bir işleme gecikmesiyle. Bu anlık push teslimatı değil, gerçek zamana yakın bir senaryodur. Aynı olay iki kez gelebilir mi? Evet, bir ağ hatasından sonra teslimat yeniden denenirse. Bu nedenle olayları kendi tarafınızda event_id alanına göre tekilleştirmek önemlidir. Olayların sıkı bir sırası garanti edilir mi? Tek bir toplu iş içinde olaylar kronolojik sırayla gelir, ancak farklı toplu işler arasında sıkı bir sıra garantisi yoktur — sıralama için her olayın datetime alanını kullanın. Çok yüksek trafik hacimlerinde ne olur? Tek bir aralıkta çok fazla olay birikirse, toplu iş truncated: true olarak işaretlenir ve verinin geri kalanı bir sonraki teslimatla gelir — bu süreçte hiçbir veri kaybolmaz. HTTPS zorunlu mu? Evet, alıcının adresi https:// ile başlamalıdır. Yerel ve dahili adresler kabul edilmez. Yalnızca tek bir link veya link grubu için olay alabilir miyim? Evet, bir webhook oluştururken hesaptaki tüm linkler yerine "Tek link" veya "Grup" kapsamını seçebilirsiniz.