Webhook Nedir? Nasıl Çalışır ve API'den Farkı Ne?

Webhook, bir sistemde belirli bir olay gerçekleştiğinde, o sistemin önceden tanımlanmış bir adrese otomatik olarak HTTP isteği göndererek başka bir sistemi haberdar etmesidir. Klasik API kullanımında siz sürekli "yeni bir şey var mı?" diye sorarsınız; webhook'ta ise karşı taraf, yeni bir şey olduğu anda size kendiliğinden haber verir. Bu yüzden webhook'lar zaman zaman "ters API" veya "geri çağrı (callback) adresi" olarak da anılır.

Yazar Haber Ajansı'nın (YHA) webhook bildirimlerini sisteminize bağlamak istiyorsanız olay türleri, imza doğrulama ve kod örnekleri için Yazar Haber Ajansı webhook belgelerine geçebilirsiniz.

Webhook'u Bir Benzetmeyle Anlamak

Bir kargo beklediğinizi düşünün. İki seçeneğiniz var:

• Sorgulama (polling): Her beş dakikada bir kargo firmasının sitesine girip "kargom geldi mi?" diye bakarsınız. Çoğu zaman cevap "hayır"dır; boşuna zaman harcarsınız ve kargo geldiğinde bunu en fazla beş dakika gecikmeyle öğrenirsiniz.
• Bildirim (webhook): Kargo firmasına telefon numaranızı bırakırsınız. Kargo kapınıza geldiğinde size mesaj gelir. Siz hiçbir şey sormazsınız; haber anında size ulaşır.

Webhook, ikinci seçeneğin yazılım dünyasındaki karşılığıdır. Hem sizin hem de kargo firmasının emeği azalır, haber de daha hızlı ulaşır. "Telefon numarası", sizin sunucunuzdaki bir URL'dir; "mesaj" ise o adrese gönderilen, olayın ayrıntılarını içeren bir HTTP isteğidir.

Webhook Nasıl Çalışır?

Bir webhook entegrasyonu dört adımda işler:

1. Kayıt: Bildirimi almak isteyen taraf, kendi sunucusunda bildirimleri karşılayacak bir adres oluşturur (ör. https://www.ornek-haber.com/yha-bildirim) ve bu adresi hizmet sağlayıcının paneline kaydeder. Genellikle hangi olaylar için bildirim almak istediğini de seçer.
2. Olay: Hizmet sağlayıcıda bir olay gerçekleşir; örneğin ajans yeni bir haber yayınlar.
3. Bildirim: Sağlayıcı, kayıtlı adrese olayın ayrıntılarını içeren bir HTTP POST isteği gönderir. İsteğin gövdesine payload denir ve çoğunlukla JSON biçimindedir.
4. Yanıt: Alıcı sunucu isteği alır ve hızlıca 200 OK gibi başarılı bir durum koduyla yanıt verir. Sağlayıcı bu yanıtı görünce bildirimin teslim edildiğini kabul eder.

Aşağıda bir haber ajansının "yeni haber yayınlandı" olayı için gönderebileceği bir payload'ın örnek hâlini görüyorsunuz. Olay ve alan adları kavramı göstermek için seçilmiştir:

{
  "olay": "haber.yayinlandi",
  "olay_id": "evt-55120",
  "zaman": "2026-10-24T14:05:03+03:00",
  "veri": {
    "haber_id": "h-102938",
    "baslik": "Merkez Bankası faiz kararını açıkladı",
    "kategori": "ekonomi",
    "url": "https://api.ornek-ajans.com/v1/haberler/h-102938"
  }
}

JSON biçimi JSON nedir yazısında anlatılıyor. Dikkat ederseniz örnek payload haberin tam metnini değil, kimliğini ve ayrıntılarına ulaşılacak adresi içeriyor. Bu yaygın bir tasarımdır: webhook "yeni bir haber var" der, alıcı sistem de haberin tamamını API'den çeker.

Webhook ile API Arasındaki Fark

Webhook ve API birbirine rakip değil, birbirini tamamlayan yöntemlerdir. Farkları şöyle özetlenebilir:

API kavramını ayrıntılı olarak API nedir yazımızda anlattık. Pratikte en sağlam yaklaşım ikisini birlikte kullanmaktır: webhook anlık tetikleyici olarak çalışır, API ise ayrıntıyı almak ve olası kaçırılmış bildirimleri telafi etmek için kullanılır. RSS beslemesini düzenli okumak da bir tür sorgulamadır; farkı RSS nedir yazımızda görebilirsiniz.

Webhook Nerelerde Kullanılır?

Webhook'lar bugün pek çok hizmetin standart özelliğidir:

• Ödeme sistemleri: Ödeme onaylandığında veya iade yapıldığında mağazaya bildirim gönderilir.
• Kod depoları: Yeni kod gönderildiğinde otomatik test ve yayın süreçleri tetiklenir.
• Form ve CRM araçları: Yeni bir form doldurulduğunda kayıt başka bir sisteme aktarılır.
• Mesajlaşma araçları: Bir olay olduğunda ekip kanalına otomatik mesaj düşer.
• Haber ve içerik dağıtımı: Ajans yeni haber yayınladığında, bir haberi güncellediğinde veya geri çektiğinde abone sistemler anında haberdar olur.

Haber dünyasında webhook'un değeri özellikle son dakika haberlerinde ortaya çıkar. Beslemeyi beş dakikada bir okuyan bir site, kritik bir gelişmeyi beş dakika geç görebilir. Webhook kullanan bir site ise haberi saniyeler içinde editörün önüne getirebilir. Bir haberin geri çekilmesi veya düzeltilmesi durumunda da bildirim anında geldiği için hatalı içeriğin sitede kalma süresi kısalır.

Webhook Güvenliği: İmza Doğrulama

Webhook adresiniz internete açık olduğu için, teorik olarak herkes o adrese istek gönderebilir. Kötü niyetli biri, sahte bir "yeni haber" bildirimi göndererek sisteminizi yanıltmaya çalışabilir. Bunu önlemenin standart yolu imza doğrulamadır:

1. Sağlayıcı ve alıcı, yalnızca ikisinin bildiği bir gizli anahtar (secret) paylaşır.
2. Sağlayıcı her bildirimin gövdesini bu anahtarla HMAC yöntemiyle (genellikle SHA-256) imzalar ve imzayı bir HTTP başlığında gönderir.
3. Alıcı, gelen gövdeyi aynı anahtarla imzalar ve sonucu başlıktaki imzayla karşılaştırır. Eşleşmiyorsa isteği reddeder.

HMAC yönteminin tanımı RFC 2104 belgesinde yer alır. Kavramı gösteren örnek bir doğrulama şöyle olabilir (başlık adı örnektir):

import hmac, hashlib

def imza_gecerli_mi(govde: bytes, gelen_imza: str, gizli_anahtar: str) -> bool:
    beklenen = hmac.new(gizli_anahtar.encode(), govde, hashlib.sha256).hexdigest()
    return hmac.compare_digest(beklenen, gelen_imza)

Burada iki ayrıntı önemlidir. Birincisi, imza ham gövde üzerinden hesaplanmalıdır; JSON'u ayrıştırıp yeniden oluşturmak boşluk ve sıra farkları nedeniyle imzayı bozar. İkincisi, karşılaştırma compare_digest gibi sabit sürede çalışan bir fonksiyonla yapılmalıdır; sıradan eşitlik karşılaştırması zamanlama saldırılarına açık olabilir.

Ek güvenlik önlemleri:

• Webhook adresi yalnızca HTTPS olmalıdır.
• Payload'daki zaman damgası kontrol edilerek eski bildirimlerin tekrar gönderilmesi (replay) engellenebilir.
• Gizli anahtar kod deposuna yazılmamalı, ortam değişkeninde tutulmalıdır.

Sağlayıcıların her birinin farklı başlık adı ve imza biçimi kullanması alıcı tarafın işini zorlaştırdığı için bu alanı ortaklaştırmaya çalışan açık bir girişim de vardır: Standard Webhooks. Bu belirtimde bildirim webhook-id, webhook-timestamp ve webhook-signature başlıklarını taşır; imzalanan metin "kimlik.zaman damgası.gövde" biçimindedir ve imza HMAC-SHA256 ile üretilip base64 olarak yazılır. Zaman damgasının imzaya dahil olması, eski bir bildirimin tekrar gönderilmesini de zorlaştırır.

Güvenilir Webhook Alıcısı Nasıl Yazılır?

Webhook almak kolaydır; güvenilir şekilde almak biraz özen ister. Dikkat edilmesi gereken başlıca ilkeler:

Hızlı yanıt verin. Sağlayıcılar genellikle birkaç saniyelik bir zaman aşımı uygular. Bildirimi aldığınızda ağır işleri (görsel indirme, veritabanına yazma, sayfa oluşturma) o anda yapmayın. Bildirimi bir kuyruğa ekleyin, hemen 200 dönün ve işi arka planda tamamlayın.

Yeniden denemelere hazırlıklı olun. Sunucunuz o an yanıt veremezse sağlayıcı aynı bildirimi bir süre sonra tekrar gönderir. Bu iyi bir şeydir; bildirim kaybolmaz. Ama aynı bildirimin birden fazla kez gelebileceği anlamına da gelir.

İşlemi tekrarlanabilir (idempotent) yapın. Her bildirimin benzersiz olay kimliğini (olay_id) kaydedin. Aynı kimlikle ikinci bir bildirim gelirse yeniden işlemeyin. Böylece aynı haber sitenizde iki kez oluşmaz.

Sıraya güvenmeyin. Ağ koşulları nedeniyle "güncellendi" bildirimi "yayınlandı" bildiriminden önce gelebilir. Olayın zaman damgasına veya API'den alacağınız güncel veriye göre karar verin.

Kaçırılanları telafi edin. Uzun süreli bir kesintide bildirimler tamamen kaybolabilir. Belirli aralıklarla API'den son haberleri kontrol eden bir yedek görev, bu boşluğu kapatır.

Kayıt tutun. Gelen bildirimleri ve işleme sonuçlarını loglamak, sorun çıktığında neyin ne zaman geldiğini anlamanızı sağlar.

Webhook mu, Sorgulama mı? Karar Rehberi

Her entegrasyonda webhook gerekmez. Aşağıdaki sorular hangi yöntemin size uygun olduğuna karar vermenize yardımcı olur:

• Hız ne kadar kritik? Son dakika haberi yayınlayan bir site için birkaç dakikalık gecikme önemlidir; webhook bu farkı kapatır. Günde birkaç kez güncellenen bir arşiv sayfası için düzenli sorgulama yeterlidir.
• Herkese açık bir HTTPS adresiniz var mı? Webhook alabilmek için sunucunuzun internetten erişilebilir olması gerekir. Yalnızca kurum içi ağda çalışan sistemler için sorgulama veya dosya tabanlı aktarım daha pratiktir.
• Olay sayısı ne kadar? Çok sık olay üreten bir kaynakta webhook, sizin göndereceğiniz binlerce boş sorgunun yerini alır ve iki tarafın da yükünü azaltır.
• Ekibinizin altyapı kapasitesi nedir? Webhook alıcısı; kuyruk, kayıt tutma ve imza doğrulama gibi bileşenler gerektirir. Bunları kuramıyorsanız hazır bir eklenti veya düzenli sorgulama daha az bakım ister.

Çoğu haber sitesi için en dengeli çözüm, webhook'u anlık tetikleyici olarak kullanmak ve yanında seyrek aralıklı bir API kontrolünü güvenlik ağı olarak tutmaktır.

Sağlayıcı Panelinde Göreceğiniz Ayarlar

Webhook sunan hizmetlerin çoğunda benzer ayarlarla karşılaşırsınız: bildirimin gönderileceği adres, abone olunacak olay türleri, imzalama için gizli anahtar, bildirimi geçici olarak durdurma seçeneği ve son gönderimlerin başarı/başarısızlık kayıtları. Bu teslimat kayıtları sorun gidermede çok değerlidir; bir bildirimin gönderilip gönderilmediğini, alıcının hangi durum koduyla yanıt verdiğini ve kaç kez yeniden denendiğini buradan görebilirsiniz.

Webhook'u Test Etmek

Geliştirme aşamasında bilgisayarınız internetten erişilebilir olmadığı için sağlayıcının bildirimleri size ulaşamaz. Bu sorunu çözmek için yerel sunucunuzu geçici olarak internete açan tünel araçları veya gelen istekleri görüntüleyen istek inceleme hizmetleri kullanılabilir. Birçok sağlayıcı ayrıca panelinde "test bildirimi gönder" özelliği sunar; bu özellikle, gerçek bir olay beklemeden alıcınızın doğru çalıştığını doğrulayabilirsiniz.

Yazar Haber Ajansı'nda Webhook Nasıl Kullanılır?

Yazar Haber Ajansı, abonelerine yeni haber, düzeltme ve iptal olduğunda kayıtlı https adreslerine POST isteğiyle bildirim gönderen webhook desteği sunar. Böylece beslemeyi veya API'yi sürekli sorgulamadan yeni haberleri kısa sürede editörlerinizin önüne getirebilir, düzeltmeleri ve iptalleri sitenize hızla yansıtabilirsiniz. YHA'nın webhook'u imza için yukarıda anlatılan Standard Webhooks yaklaşımını kullanır; varsayılan olarak bildirimde haberin tam içeriği gelir, isterseniz yalnızca kimlik ve adresin geldiği "ince" yükü seçip ayrıntıyı API'den alabilirsiniz. Yanıt vermeyen adrese bildirim yaklaşık 24 saat boyunca artan aralıklarla yeniden denenir ve sıra garantisi yoktur; bu yüzden olay kimliğiyle ayıklama ve sürüm numarasıyla eski düzeltmeyi yok sayma önerileri YHA için de geçerlidir. Olay türleri, gövde alanları, imza doğrulama, yeniden deneme kuralları ile Python, JavaScript (Node) ve C# örnekleri Yazar Haber Ajansı webhook belgelerinde anlatılıyor.

Webhook, API ve diğer otomatik çıkışlar abonelik paketine sözleşmeyle eklenir; paketinizde webhook kanalı açık değilse bu yol kullanılamaz.

Bildirimi aldıktan sonra haberin tamamını ya da kaçırdığınız olayları çekmek için YHA API belgelerine bakabilirsiniz. Tüm entegrasyon seçeneklerini Yazar Haber Ajansı geliştirici belgeleri sayfasında karşılaştırabilirsiniz.

Sıkça Sorulan Sorular

Webhook kullanmak için sunucu gerekir mi?

Evet. Bildirimleri karşılayabilmek için internetten erişilebilen, HTTPS destekli bir adrese ihtiyacınız vardır. Bu adres kendi sunucunuz, barındırma hizmetiniz veya sunucusuz (serverless) bir fonksiyon olabilir.

Webhook ile API aynı şey mi?

Hayır. API'de istemci sorar ve sunucu cevap verir. Webhook'ta ise olay olduğunda sağlayıcı istemciye kendiliğinden bildirim gönderir. İkisi genellikle birlikte kullanılır.

Webhook bildirimi gelmezse ne olur?

Sağlayıcılar genellikle başarısız bildirimleri belirli aralıklarla yeniden dener. Yine de uzun kesintilere karşı API ile düzenli kontrol yapan bir yedek görev kurmak iyi bir uygulamadır.

Webhook güvenli mi?

İmza doğrulama, HTTPS ve zaman damgası kontrolü uygulandığında güvenlidir. Bu önlemler olmadan webhook adresinize sahte istekler gönderilebilir.

Aynı bildirim iki kez gelirse ne yapmalıyım?

Her bildirimin olay kimliğini kaydedin ve daha önce işlenmiş bir kimlik geldiğinde tekrar işlemeyin.