Webhook Nedir? API'den Farkları, Avantajları ve Entegrasyon İpuçları

Webhook, bir sistemin başka bir sisteme gerçekleşen bir olayı otomatik olarak bildirmesini sağlayan bir mekanizmadır. Uygulama, sürekli sunucuya istekte bulunmak yerine, verileri tam olarak oluştukları anda alır: örneğin başarılı bir ödeme, yeni bir sipariş veya teslimat durumunun değişmesi gibi.

Webhook'lar, birden fazla servisin entegre olduğu senaryolarda özellikle faydalıdır. Gereksiz istek sayısını azaltır ve sistemlerin değişikliklere daha hızlı tepki vermesini sağlar. Webhook, geleneksel API ile yakından ilişkilidir, ancak farklı bir prensiple çalışır.

Webhook nedir ve neden kullanılır?

Webhook'u basitçe anlatmak

API ve webhook farkını en kolay bildirimler üzerinden açıklayabiliriz.

Geleneksel API kullanımında uygulama, diğer sunucuya gidip "Yeni veri var mı?" diye sorar. Bir değişiklik yoksa, bir süre sonra aynı isteği tekrarlar.

Webhook ise tam tersini yapar. Uygulama, servise özel bir adres (URL) bildirir; ilgili olay gerçekleştiğinde servis bu adrese isteği kendisi gönderir.

Örneğin, bir e-ticaret sitesinin ödeme sistemine her saniye "Kullanıcı ödedi mi?" diye sorması gerekmez. Ödeme servisi, ödeme onaylandığında otomatik olarak webhook gönderir.

Bu yüzden webhook'lar, programlar arası bildirim mekanizması olarak bilinir. Bir sistem diğerinin durumunu sürekli sormaz, yalnızca önemli bir olay olduğunda mesaj alır.

Webhook'lar hangi sorunları çözer?

Webhook, bir sistemin başka bir servisteki değişikliğe hızlıca tepki vermesi gereken durumlarda kullanılır. Tipik örnekler:

• Ödeme sistemi mağazaya başarılı ödemeyi bildirir,
• CRM, web sitesinden gelen yeni başvuruyu alır,
• Teslimat servisi siparişin yeni durumunu iletir,
• Git platformu yeni kod yüklendiğinde derleme başlatır,
• Mesajlaşma uygulaması, bota yeni mesajı iletir,
• Bulut servisi, dosya işlenmesinin tamamlandığını bildirir.

Bu senaryoların ortak noktası, aksiyonun bir olay tarafından tetiklenmesidir. Sistem, verileri belirli aralıklarla kontrol etmez; yalnızca gerçekten bir şey olduğunda bildirim alır.

Bu prensip sadece küçük entegrasyonlarda değil, büyük yazılım sistemlerinde de yaygın olarak kullanılır. Daha fazlası için Event-driven mimarinin modern sistemlerde performans avantajları makalesine göz atabilirsiniz.

Bu sayede webhook, otomasyon için oldukça elverişlidir. Olayı alan program, sipariş statüsünü güncelleyebilir, kullanıcıya bildirim gönderebilir, veritabanına kayıt ekleyebilir veya başka bir süreci başlatabilir.

Webhook nasıl çalışır?

Olay, URL ve HTTP isteği

Webhook'un çalışabilmesi için öncelikle alıcı sistemin özel bir URL (endpoint) oluşturması gerekir. Diğer servis, bildirimleri bu adrese gönderir.

Akış şu şekildedir: olay gerçekleşir → servis veriyi hazırlar → HTTP isteği gönderir → alıcı sistem isteği işler.

Örneğin, bir kullanıcı siparişi öder. Ödeme servisi işlemin başarılı olduğunu kaydeder ve e-ticaret sitesinin webhook URL'sine HTTP isteği yollar. Mağaza, bu isteği alır almaz siparişin durumunu "Ödendi" olarak günceller ve gerekirse ek işlemler başlatır.

Çoğu zaman, HTTP POST metodu tercih edilir çünkü olayla ilgili veriler istekle birlikte iletilir. Ancak, kullanılacak HTTP metodu servise bağlı olarak değişebilir.

Bir webhook isteğinin içeriği

Webhook isteği genellikle birkaç bölümden oluşur. URL, işleyici adresidir; HTTP başlıklarında hizmet verisi olabilir ve asıl olay bilgisi istek gövdesinde yer alır.

Birçok servis, verileri JSON formatında yollar. Örneğin, ödeme bildirimi şu alanları içerebilir: sipariş ID'si, tutar, para birimi, ödeme durumu ve işlem zamanı.

{
  "event": "payment.success",
  "order_id": "A1024",
  "status": "paid"
}

Uygulama, gelen istekteki event alanını kontrol ederek olay tipini belirler ve uygun işlemi başlatır. Ödeme ile ilgiliyse siparişi ödenmiş olarak işaretler, teslimat ise durumu günceller.

İşlem sonrası webhook sunucusu genellikle bir HTTP yanıt kodu döner. 200 serisi bir kod, isteğin başarıyla alındığını gösterir. Hata dönerse veya hiç yanıt gelmezse, gönderen servis olayı yeniden göndermeye çalışabilir.

Webhook işleyişine bir örnek

Bir e-ticaret sitesi dış bir ödeme sistemine bağlı olsun.

Müşteri siparişi tamamlar ve ödeme sayfasına geçer. Ödeme sonrası servis, bankadan onay alır. Mağaza, işlemin sonucunu henüz bilmez.

Mağaza, ödemeyi sürekli API ile kontrol etmek yerine, ödeme sistemi şöyle bir webhook gönderir:

payment.success → mağazanın webhook'u → sipariş durumu güncellenir

Mağaza sunucusu bildirimi alır, verileri doğrular ve siparişi otomatik olarak "Ödendi" durumuna çeker. Ardından fatura gönderme, depoyu bilgilendirme ve ürün hazırlama gibi işlemler tetiklenebilir.

Bu yaklaşım, olayın ilk istekten saniyeler, dakikalar hatta saatler sonra gerçekleşebileceği süreçlerde özellikle faydalıdır. Uygulamanın sürekli durumu kontrol etmesine gerek kalmaz - sadece webhook'u bekler.

Webhook ve API: Aralarındaki farklar

API talep ile, webhook olay ile çalışır

Webhook ve geleneksel API arasındaki temel fark, veri alışverişini kimin başlattığıdır.

API ile çalışırken uygulama, sunucuya kendisi istekte bulunur. Örneğin; sipariş listesini almak, kullanıcı profilini sorgulamak ya da ödeme durumunu öğrenmek için. Sunucu, yalnızca böyle bir istek geldiğinde yanıt verir.

Webhook ise farklı bir mantık izler. Alıcı önceden URL'sini bildirir, servis ise istenen olay meydana geldiğinde otomatik olarak isteği gönderir.

Bunu iki modelle özetleyebiliriz:

• API - "Bir şey oldu mu diye sormak"
• Webhook - "Bir şey olunca haber almak"

Teknik dokümantasyonda bu yaklaşımlar genellikle pull ve push modelleriyle ilişkilendirilir. API çoğunlukla pull (çekme), webhook ise push (itme) mekanizmasıdır.

Webhook vs REST API

Webhook ve REST API aynı temel internet teknolojilerini kullanır: HTTP, URL, başlıklar, sorgu metotları ve JSON gibi veri formatları. Ancak amaçları farklıdır.

API üzerinden mağaza belirli bir ödemenin bilgisini isteyebilir. Webhook ile ödeme sistemi, ödemenin tamamlandığını otomatik olarak bildirir.

Webhook ve API'yi tamamen birbirinin alternatifi görmek doğru değildir.

Webhook, API'nin yerine geçmez

Pratikte webhook ve API genellikle birlikte kullanılır.

API, uygulamanın verileri kendisinin alması veya değiştirmesi gerektiğinde kullanılır. Webhook ise bir olaydan hızlıca haberdar olmak için idealdir.

Örneğin bir CRM sistemi düşünelim. API ile müşteri kartı alınabilir, telefon numarası değiştirilebilir veya sipariş geçmişi sorgulanabilir. Webhook ise sisteme yeni bir müşteri eklendiğinde veya işlem aşaması değiştiğinde harici sistemleri bilgilendirir.

Bazen webhook, yalnızca nesne kimliği ve olay tipi gibi minimum veri yollar. Uygulama bu bilgileri aldıktan sonra API'ye başvurarak tam detayları çekebilir.

Bu model, gereksiz istekleri azaltırken API'nin esnekliğini de korur.

Webhook ne zaman, API ne zaman tercih edilmeli?

Webhook ne zaman daha uygundur?

Webhook, sistemin bir olaydan hemen sonra haberdar olması gereken durumlar için daha uygundur.

Tipik örnekler: ödeme onayı, yeni sipariş oluşturulması, teslimat durumunun değişmesi, CRM'de yeni potansiyel müşteri, dosya yüklemesi veya kod paylaşımı.

Böyle senaryolarda API'ye sürekli istek atmak gereksiz yük oluşturur. Uygulama her dakika sunucuyu sorgulasa bile çoğu istek aynı sonucu dönebilir. Webhook, yalnızca gerçek bir değişiklik olduğunda tetiklenir.

Bu nedenle webhook'lar, süreç otomasyonu ve olaylara hızlı tepki gereken servis entegrasyonları için idealdir.

API ne zaman daha uygundur?

Geleneksel API, uygulamanın veriye istediği zaman erişmesi gerektiğinde daha uygundur.

Örneğin, kullanıcı e-ticaret sitesinde siparişlerini görmek istediğinde, uygulama API'ye istek gönderir ve güncel listeyi alır.

API ayrıca şu durumlar için gereklidir:

• Arama yapmak,
• Nesne listesi almak,
• Kayıt oluşturmak veya güncellemek,
• Veri silmek,
• Kimliğe göre detaylı bilgi sorgulamak,
• Sunucuya başvuru zamanını uygulamanın belirlemesi gerektiğinde.

Webhook bu tür işlemler için uygun değildir. Olay bildirimi yapar, ancak istenilen anda rasgele veri çekmeye izin vermez.

Pratikte sıkça kullanılan hibrit modelde, webhook bir değişikliği haber verir, ardından uygulama API'ye başvurarak gerekli detayları çeker.

Webhook, polling ve WebSocket

Webhook, başka bir servisten güncellemeleri almak için tek yol değildir. Göreve göre polling veya WebSocket de tercih edilebilir.

Polling, sunucuya düzenli aralıklarla istek göndermektir. Örneğin, uygulama her 10 saniyede bir API'ye "Yeni mesaj var mı?" diye sorar. Uygulaması kolaydır, ancak gereksiz birçok sorgu sistem kaynaklarını tüketir.

Webhook, sürekli bağlantı kurmaz. Servis, yalnızca önceden tanımlanmış bir olay gerçekleşince bağımsız bir HTTP isteği gönderir. Özellikle sunucu entegrasyonları, bildirimler ve otomasyon için uygundur.

WebSocket, istemci ile sunucu arasında sürekli iki yönlü bir bağlantı kurar. Her iki taraf da istedikleri anda veri gönderebilir. Sohbet uygulamaları, online oyunlar, ticaret panelleri gibi gerçek zamanlı iletişim gerektiren uygulamalar için idealdir.

Sürekli bağlantının detayları için WebSocket teknolojisi nedir ve nasıl çalışır? makalesini inceleyebilirsiniz.

Seçim, veri akışının doğasına göre yapılır: Uygulama bilgiyi istediği zaman çekmek istiyorsa API, olaylara otomatik tepki gerekiyorsa webhook, sürekli ve gerçek zamanlı veri akışı gerekiyorsa WebSocket kullanılır.

Webhook nasıl kurulur ve nelere dikkat edilmeli?

Webhook endpoint oluşturma

Webhook için alıcı sistemin, harici servisin HTTP isteklerini gönderebileceği herkese açık bir URL'ye ihtiyacı vardır. Bu adrese webhook endpoint denir.

Geliştirici, gelen verileri karşılayıp doğrulayacak ve gerekli işlemleri yapacak bir işleyici oluşturur. Ardından bu URL, kaynak servisin ayarlarında belirtilir.

Örneğin bir endpoint şöyle olabilir:

https://example.com/webhooks/payment

İlgili olay gerçekleştiğinde, servis isteği tam olarak bu adrese gönderir.

Endpoint'in internete açık ve HTTPS destekli olması gerekir. Yerel geliştirme sırasında, geliştiricinin bilgisayarına geçici olarak açık adres sağlayan tünel veya test servisleri kullanılabilir.

Webhook doğrulama

Webhook endpoint'i dış isteklere açıktır, bu yüzden gelen her isteğe güvenmemelisiniz.

Kötü niyetli biri endpoint adresini öğrenirse sahte bir olay göndermeye çalışabilir. Bu nedenle, çoğu servis webhook isteklerini gizli anahtarla imzalar.

Alıcı sistem, gelen isteğin imzasını kendi hesaplar ve servisin gönderdiğiyle karşılaştırır. Eşleşirse, verinin kaynaktan geldiği ve yolda değiştirilmediği doğrulanır.

Ek olarak, gizli token'lar, HTTPS kontrolü ve IP kısıtlamaları (eğer servis destekliyorsa) kullanılabilir.

Tekrar gönderimler ve kopya olaylar

Webhook, isteğin ilk denemede mutlaka başarıyla işleneceğini garanti etmez. Sunucu geçici olarak kapalı olabilir, bağlantı kesilebilir veya işlem uzun sürebilir.

Bu yüzden birçok platform tekrar gönderim (retry) mekanizması uygular. Endpoint hata döner ya da zamanında yanıt vermezse, servis bildirimi yeniden yollar.

Bu durumda, aynı olay birden fazla kez gelebilir. Uygulamanız kopyaları tanıyıp işlemi tekrar yapmamalıdır.

Özellikle ödemelerde bu önemlidir. Aynı başarılı ödeme bildirimi iki kez gelirse, sistem bakiyeyi veya siparişi çift oluşturmamalı, ürünü iki kere göndermemelidir.

Bunu önlemek için genellikle olay kimliği kullanılır. Uygulama, işlemi yapmadan önce aynı ID'nin daha önce işlenip işlenmediğini kontrol eder. Buna idempotent (tekrarlanabilir) işlem denir.

Kayıtlar ve yanıt kodları

Webhook alındıktan sonra sunucu, HTTP yanıt kodu döner. Başarılı işleme genellikle 200 serisi bir kodla onay verilir.

Sunucu hata dönerse, dış servis teslimatın başarısız olduğunu varsayarak tekrar deneme yapabilir.

Uzun süren işlemleri doğrudan webhook endpoint'inde yapmak önerilmez. Olayı hızlıca doğrulayıp beklemeye almadan başarılı yanıt dönebilir, ağır işlemler sonradan kuyruktan yürütülebilir.

Kayıt tutmak da önemlidir. Olayın alınma zamanı, türü, kimliği ve işlenme sonucu kaydedilmelidir. Böylece bir bildirimin neden işlenmediği veya neden tekrar gönderildiği analiz edilebilir.

Doğru yapılandırılmış bir webhook endpoint, yalnızca POST isteklerini karşılayan bir URL değildir. Sağlam bir entegrasyon, kaynak doğrulama, tekrar gönderim, kopya kontrolü, hata ve geçici erişilememe gibi detayları içermelidir.

Sonuç

Webhook, bir sistemin başka bir sisteme gerçekleşen olayı otomatik olarak bildirmesini sağlar; API üzerinden sürekli sorgulama gerektirmez. Bu, ödemeler, bildirimler, servis entegrasyonları ve otomasyon gibi değişikliklere hızlıca tepki gerektiren süreçler için idealdir.

Webhook ile API arasındaki ana fark, veri akışının yönünde yatar. API'de istemci veriyi talep eder; webhook'ta ise kaynak servis, olay sonrası bildirimi gönderir. Webhook API'nin yerine geçmez, genellikle birlikte kullanılırlar.

Veriyi istenen anda çekmek, arama yapmak veya nesneleri değiştirmek için API; belirli olaylara otomatik tepki vermek için webhook; gerçek zamanlı sürekli veri akışı için ise genellikle WebSocket kullanılır.

Webhook uygularken, yalnızca HTTP isteğini göndermekle kalmayıp; güvenlik, imza doğrulama, tekrar gönderim, kopya olay kontrolü ve hata yönetimi gibi kritik konulara da dikkat etmek gerekir. Tüm bu ayrıntılar, basit bir webhook endpoint'ini servisler arası sağlam bir entegrasyona dönüştürür.