Webhook Nedir? Sistemler Arası Anlık Bildirim

Müşteriniz ödemeyi tamamladığı anda siparişin “hazırlanıyor” durumuna geçmesini, kargo teslim edildiği anda müşteriye mesaj gitmesini istiyorsunuz. Bunun için sisteminizin her dakika ödeme kuruluşuna “ödeme geldi mi?” diye sorması mı gerekir, yoksa ödeme kuruluşu size kendiliğinden mi haber vermeli? İkinci yolun adı webhook’tur. Webhook nedir sorusunun kısa cevabı şu: Bir sistemde belirli bir olay gerçekleştiğinde, o sistemin önceden belirlenmiş bir adrese otomatik olarak HTTP isteği göndererek diğer sisteme haber vermesidir. Bu yazıda nasıl çalıştığını, nerelerde kullanıldığını ve güvenli kurulumun kurallarını anlatacağım.

Sormak mı, haber almak mı?

Klasik bir API kullanımında istemci soru sorar, sunucu cevap verir. Bir siparişin ödeme durumunu öğrenmek için sisteminiz düzenli aralıklarla sorgu gönderir. Buna yoklama (polling) denir. Çoğu sorgunun cevabı “değişiklik yok” olduğu için hem iki taraf gereksiz yere yorulur hem de bilgi, sorgu aralığı kadar gecikmeli gelir.

Webhook bu ilişkiyi tersine çevirir. Siz karşı tarafa bir adres verirsiniz; olay olduğunda karşı taraf size gelir. Bir benzetmeyle: Kargonuzun gelip gelmediğini öğrenmek için her saat kapıya bakmak yoklamadır, kuryenin zili çalması webhook’tur. API kavramına yabancıysanız önce API nedir yazısına göz atabilirsiniz.

	Yoklama (polling)	Webhook
Kim başlatır?	Bilgiyi isteyen sistem	Olayın gerçekleştiği sistem
Bilgi ne zaman gelir?	Bir sonraki sorguda	Olay olur olmaz
Kaynak kullanımı	Boşa giden çok sayıda istek	Yalnızca olay olduğunda istek
Kurulum	Basit	Herkese açık bir adres ve doğrulama gerekir

Webhook nedir, nerelerde karşınıza çıkar?

Webhook’lar, işletmelerin günlük operasyonunda sandığınızdan çok daha yaygındır:

• Online ödeme: Ödeme kuruluşu, ödemenin başarılı, başarısız veya iade edildiğini sitenize bildirir. Sanal POS entegrasyonunun genel çerçevesi için sanal POS entegrasyonu yazısına bakabilirsiniz.
• Kargo: Gönderi şubeye ulaştığında, dağıtıma çıktığında veya teslim edildiğinde durum bildirimi gelir. Ayrıntılar kargo entegrasyonu yazısında.
• Mesajlaşma: Bir müşteri WhatsApp hattınıza yazdığında mesaj, webhook ile sizin sunucunuza iletilir; chatbot’lar bu şekilde çalışır.
• Form ve CRM: Sitenizdeki formdan yeni bir talep geldiğinde CRM’e kayıt açılır, satış ekibine bildirim düşer.
• Yazılım geliştirme: Kod deposuna yeni bir değişiklik gönderildiğinde otomatik test ve yayın süreci başlar.

Üçüncü taraf servislerin hangi olaylar için webhook sunduğu, bildirim biçimi ve tekrar deneme kuralları sağlayıcıdan sağlayıcıya değişir; güncel ayrıntıları ilgili sağlayıcının dokümantasyonundan kontrol edin.

Bir webhook isteğinin içinde ne olur?

Webhook nedir sorusunu teknik açıdan da kısaca cevaplayalım.Webhook genellikle sizin belirlediğiniz adrese gönderilen bir POST isteğidir. Gövdesinde olayın türü (ör. “ödeme başarılı”), olayın benzersiz kimliği, zamanı ve ilgili veriler (sipariş numarası, tutar, durum) JSON biçiminde yer alır. Çoğu sağlayıcı ayrıca isteğin gerçekten kendisinden geldiğini kanıtlamak için bir imza başlığı ekler.

Güvenli ve sağlam bir webhook alıcısı nasıl kurulur?

Webhook adresiniz internete açıktır; dolayısıyla herkes oraya istek gönderebilir. Sahte bir “ödeme başarılı” bildirimiyle sipariş onaylatmak, dikkat edilmezse mümkün olabilir. Sağlam bir kurulum için şu kurallar önemlidir:

1. İmzayı doğrulayın

Sağlayıcı, isteğin gövdesini paylaşılan gizli anahtarla imzalar. Sunucunuz aynı hesabı yapıp sonucu karşılaştırır. PHP’de basit bir örnek:

$payload = file_get_contents('php://input');
$expected = hash_hmac('sha256', $payload, $secret);
if (!hash_equals($expected, $receivedSignature)) {
    http_response_code(401);
    exit;
}

İmza formatı ve başlık adı sağlayıcıya göre değişir; doğrulama her zaman onun dokümanına göre yapılmalıdır. Kritik işlemlerde, bildirimi aldıktan sonra sağlayıcının API’sine ayrıca sorup durumu teyit etmek ek bir güvence sağlar.

2. Hızlı cevap verin, işi sonra yapın

Sağlayıcılar genellikle kısa bir süre içinde başarılı (2xx) cevap bekler; alamazlarsa isteği tekrar gönderebilir. Bu yüzden alıcı, bildirimi kaydedip hemen cevap vermeli; e-posta gönderme, fatura kesme gibi uzun işleri bir kuyruğa bırakmalıdır.

3. Aynı bildirimin iki kez gelmesine hazırlıklı olun

Ağ sorunları ve tekrar denemeler nedeniyle aynı olay birden fazla kez gelebilir. Olay kimliğini kaydedip daha önce işlenmiş bildirimi atlamak (idempotency), aynı siparişin iki kez onaylanmasını ya da müşteriye iki kez mesaj gitmesini önler.

4. Sıra garantisine güvenmeyin

“Teslim edildi” bildirimi, “dağıtıma çıktı” bildiriminden önce gelebilir. Durum güncellemelerinde olay zamanına bakmak ya da geriye doğru durum değişikliğini engellemek gerekir.

5. Kayıt tutun ve izleyin

Gelen her bildirimi, işlenme sonucuyla birlikte kaydedin. Bir sorun olduğunda “bildirim hiç gelmedi mi, geldi de işlenemedi mi?” sorusunun cevabı bu kayıtlardadır. Entegrasyonlarda sık görülen sorunları API entegrasyon hataları yazısında derledim.

Bu işi nasıl birlikte yaparız?

Sisteminize webhook ile çalışan bir entegrasyon kurmak istediğinizde şu adımları izliyorum:

1. Olayları belirleme: Hangi olayın (ödeme, kargo, form, mesaj) sisteminizde hangi işlemi tetiklemesi gerektiğini birlikte listeleriz.
2. Sağlayıcıyı inceleme ve teklif: Bağlanılacak servisin webhook dokümanını inceler, imza ve tekrar deneme kurallarını netleştirip teklif hazırlarım.
3. Geliştirme ve test: Alıcıyı imza doğrulama, kuyruk ve tekrar koruması ile kurar; sahte, tekrarlanan ve sırasız bildirim senaryolarını test ederim.
4. Teslim ve izleme: Kayıt ekranını ve hata uyarılarını devreye alır, sonrasında oluşabilecek sağlayıcı değişikliklerinde destek veririm.

Entegrasyon ihtiyacınızı anlatmak için iletişim sayfasından bana ulaşabilirsiniz.

Sık sorulan sorular

Webhook ile API arasındaki fark nedir?

API’de siz soru sorarsınız, karşı taraf cevap verir. Webhook’ta ise olay gerçekleştiğinde karşı taraf size kendiliğinden haber verir. Çoğu entegrasyonda ikisi birlikte kullanılır.

Webhook için ayrı bir sunucu gerekir mi?

Genellikle gerekmez. Mevcut web sitenizin veya uygulamanızın sunucusunda, internete açık ve HTTPS ile çalışan bir adres yeterlidir.

Sunucum kapalıyken gelen bildirimler kaybolur mu?

Pek çok sağlayıcı başarısız bildirimleri belirli bir süre boyunca tekrar dener, ancak bu kurallar sağlayıcıya göre değişir. Kritik verilerde düzenli bir mutabakat sorgusuyla eksikleri tamamlamak iyi bir pratiktir.

WordPress ve WooCommerce webhook destekler mi?

Evet. WooCommerce, sipariş ve ürün olayları için webhook tanımlamaya imkân verir; ödeme eklentileri de sağlayıcılardan gelen bildirimleri webhook ile alır.

Sonuç

Webhook nedir sorusunun işletme için anlamı, sistemlerinizin birbirine sormadan haber vermesi ve böylece işlemlerin anında, elle müdahale olmadan ilerlemesidir. İmza doğrulama, tekrar koruması ve kayıt tutma ile kurulduğunda güvenilir bir otomasyon temeli oluşturur. Kendi entegrasyonunuzu birlikte planlamak isterseniz bana yazabilirsiniz.