Webhook Nedir? Uygulamalar Birbirine Nasıl Haber Verir

Webhook, bir şey olduğu anda bir servisin uygulamanıza gönderdiği otomatik bir mesajdır. Bir müşterinin ödemesi başarılı olduğunda Stripe, uygulamanızdaki bir adrese "ödeme başarılı, ayrıntılar şunlar" diyen bir webhook gönderir ve uygulamanız tepki verir — siparişi ödendi olarak işaretler, makbuz gönderir, hesabın kilidini açar. Kısacası: API, uygulamanızın başka bir servise soru sormasıdır; webhook ise diğer servisin uygulamanızı arayıp bir şey bildirmesidir.

AI ile geliştirirken neden önemli?

Uygulamanız ödeme alır, başka bir araçtan form gönderimleri alır ya da GitHub, Shopify veya bir takvim gibi servislere bağlanırsa, webhook'larla karşılaşırsınız. Bir şeyin olduğunu öğrenmenin genellikle doğru yolu bunlardır; ama AI ile yapılmış uygulamaların en sık ince hatalar yaptığı yer de burasıdır:

• Uç nokta her isteği kabul eder, dolayısıyla herkes sahte bir "ödeme başarılı" olayı gönderebilir.
• Uygulama, erişimi webhook yerine ödeme yönlendirme sayfasında verir; bu yüzden sekmeyi erken kapatan insanlar ödedikleri şeyi alamaz, başarı URL'sini bulan insanlar ise ücretsiz alır.
• Aynı olay iki kez gelir ve müşteri iki sipariş ya da iki e-posta alır.

Webhook'ların nasıl çalıştığını bilmek, korumaları baştan istemenizi sağlar.

Günlük hayattan bir benzetme: teslimat mesajı

Paketinizin gelip gelmediğini iki şekilde öğrenebilirsiniz. Her on dakikada bir ön kapıya kadar yürüyüp kontrol edebilirsiniz (buna polling denir — uygulamanızın "yeni bir şey var mı?" diye tekrar tekrar bir API çağırması). Ya da kurye teslim edildiğinde size mesaj atabilir (işte bu bir webhook).

Mesaj açıkça daha iyidir — ona güvenebildiğiniz sürece. Herkes size "paket teslim edildi" mesajı gönderebiliyorsa, bunun gerçekten kuryeden geldiğini bilmenin bir yolunu istersiniz. Mesaj geldiğinde telefonunuz kapalıysa da kuryenin sonra tekrar denemesini istersiniz. Bu iki kaygı — doğrulama ve yeniden deneme — webhook'ları zorlaştıran şeylerin çoğunluğunu oluşturur.

Webhook adım adım nasıl çalışır?

1. Uygulamanızın backend'inde bir uç nokta oluşturursunuz: POST isteklerini kabul eden https://yourapp.com/webhooks/stripe gibi bir URL.
2. Bu URL'yi sağlayıcıya kaydedersiniz ve hangi olayları istediğinizi seçersiniz (örneğin "checkout tamamlandı" ve "abonelik iptal edildi").
3. Sağlayıcı size bir imzalama anahtarı verir. Bunu sunucunuzda bir gizli bilgi olarak saklarsınız — bkz. ortam değişkenleri ve gizli bilgiler.
4. Bir olay gerçekleşir. Sağlayıcı, olayı anlatan bir JSON gövdesi ve bir imza başlığıyla birlikte URL'nize bir HTTP isteği gönderir.
5. Uygulamanız imzayı doğrular, olay kimliğini kaydeder, hızlıca bir başarı kodu (200) yanıtlar ve ardından işi yapar.
6. Uygulamanız başarı yanıtı vermezse, birçok sağlayıcı daha sonra tekrar dener.

İmzalar

Bir imza, isteğin sağlayıcıdan geldiğini ve değiştirilmediğini kanıtlar. Örneğin Stripe, imzalama anahtarını kullanarak istek gövdesi ve bir zaman damgası üzerinden SHA-256 ile bir HMAC (anahtarlı bir parmak izi türü) hesaplar ve bunu bir Stripe-Signature başlığında gönderir. Uygulamanız, anahtarının kendi kopyasıyla aynı hesaplamayı yapar; sonuçlar eşleşirse istek gerçektir. Zaman damgası da imzalandığı için, birinin kaydedip daha sonra tekrar oynattığı eski istekleri reddedebilirsiniz — Stripe'ın kütüphaneleri, Eylül 2026 itibarıyla dokümantasyonuna göre varsayılan olarak beş dakikalık bir tolerans kullanır.

Pratik bir ayrıntı: imza, isteğin ham gövdesi üzerinden hesaplanır. Çerçeveniz doğrulamadan önce JSON'u ayrıştırıp yeniden biçimlendirirse kontrol başarısız olur. Bu çok yaygın bir hatadır.

Yeniden denemeler, tekrarlar ve sıra

Sağlayıcılar farklı davranır, bu yüzden her birinin dokümantasyonunu kontrol edin. Eylül 2026 itibarıyla:

Stripe dokümantasyonu ayrıca olayların gerçekleştikleri sırayla geleceğinin garanti edilmediğini ve aynı olayın nadiren birden çok kez gelebileceğini belirtir; bu yüzden olay kimliklerini takip etmeyi önerir.

Genel ders her sağlayıcı için geçerlidir: olaylar geç, birden çok kez ve sırasız gelebilir. İşleyiciniz idempotent olmalıdır — aynı olayı iki kez işlemek, bir kez işlemekle aynı sonucu verir.

Çalışılmış bir örnek: ücretli bir kursun kilidini açmak

Online bir kurs satıyorsunuz. Bir öğrenci Satın Al düğmesine tıklıyor, Stripe'ın barındırdığı ödeme sayfasında ödüyor ve sitenize geri dönüyor.

Kırılgan yol: "teşekkürler" sayfası kursun kilidini açar. Öğrenci yönlendirme sırasında tarayıcıyı kapatırsa ödemiş ama erişimi olmamıştır. Birisi teşekkür sayfasının URL'sini tahmin ederse, ödeme yapmadan erişim kazanır.

Webhook yolu:

1. Stripe ödemeyi onayladığında /webhooks/stripe adresine bir checkout.session.completed olayı gönderir.
2. Backend'iniz imzayı imzalama anahtarıyla doğrular. Doğrulama başarısızsa 400 yanıtlar ve hiçbir şey yapmaz.
3. Bu olay kimliğinin daha önce işlenip işlenmediğini kontrol eder. Evetse 200 yanıtlar ve durur.
4. Olay kimliğini kaydeder, 200 yanıtlar, ardından öğrenciye erişim verir ve bir hoş geldin e-postası gönderir.
5. Teşekkür sayfası yalnızca "Ödeme alındı — kursunuz birazdan görünecek" der ve öğrencinin erişim durumunu kontrol eder.

Daha sonra bir abonelik iptal edilirse ya da bir kart reddedilirse, diğer webhook olayları uygulamanıza erişimi kaldırmasını ya da duraklatmasını söyler. Abonelik ürünleri faturalamayla bu şekilde senkron kalır — bkz. SaaS nedir ve uygulamanıza ödeme nasıl eklenir.

Temel terimler

• Uç nokta (endpoint): Uygulamanızdaki webhook'ları alan URL.
• Olay / payload: Ne olduğu ve bunu anlatan veri (genellikle JSON).
• İmzalama anahtarı (signing secret): İmzaları doğrulamak için kullanılan paylaşılmış gizli anahtar.
• İdempotent: Aynı sonucu vererek birden çok kez çalıştırmak güvenlidir.
• Polling: Bir webhook beklemek yerine değişiklikler için tekrar tekrar bir API sormak.
• Tünel: Geliştirme sırasında webhook'ların ulaşabilmesi için bir dizüstü bilgisayara geçici bir genel URL veren araç.

Yaygın hatalar ve yanlış anlamalar

• İmzaları doğrulamamak. Uç nokta URL'si gizli değildir. Doğrulama, isteği güvenilir kılan şeydir.
• Yanıt vermeden önce yavaş iş yapmak. Yanıt vermeden önce e-posta göndermek ya da PDF üretmek zaman aşımlarına yol açar; bu da yeniden denemeleri, yeniden denemeler de tekrarları tetikler.
• Tam olarak bir kez, sırayla geleceğini varsaymak. Olay kimliklerini kaydedin ve varış sırasına güvenmeyin.
• Önizleme URL'si kullanmak. Webhook'ların sabit, genel bir adrese ihtiyacı vardır. Özel önizlemeler ve localhost internetten erişilemez; yayınlanmış URL'nizi (ya da test sırasında bir tüneli) kullanın.
• Test ve canlı gizli bilgileri karıştırmak. Sağlayıcılar test ve canlı modlar için genellikle farklı imzalama anahtarları verir. İkisini de saklayın ve doğru olanı kullanın.
• Önemli kararlar için payload'a körü körüne güvenmek. Yüksek riskli işlemlerde, olayı aldıktan sonra sağlayıcının API'sinden en güncel durumu çekmek mantıklıdır.

AI oluşturucunuzdan ne istemelisiniz

Sunucuda bir POST /webhooks/stripe uç noktası ekle. Stripe imzasını ham istek gövdesini ve STRIPE_WEBHOOK_SECRET gizli anahtarını kullanarak doğrula. Geçersiz imzaları 400 ile reddet. Her olay kimliğini kaydet ve daha önce işlenmiş olayları atla. Hızlıca 200 yanıtla, ardından checkout.session.completed olayını siparişi ödendi olarak işaretleyip makbuz göndererek işle. Olay türünü logla. Erişimi checkout başarı sayfasından verme.

Ardından test edin: sağlayıcının panelinden bir test olayı gönderin, aynısını bir kez daha gönderin ve yanlış bir imzayla bir istek yollayın. Yalnızca ilki bir şeyi değiştirmelidir.

Mythex'te webhook'lar

Mythex ayrı bir webhook servisi çalıştırmaz; agent'tan uygulamanızın kendi backend'ine bir webhook uç noktası eklemesini istersiniz ve sağlayıcıyı yayınlanmış URL'nize yönlendirirsiniz, çünkü webhook'ların genel bir adrese ihtiyacı vardır. İmzalama anahtarı proje gizli bilgilerinize girer ve canlı bir uygulamada değiştirirseniz yeniden yayınlarsınız. Webhook'ları işleme docs tarifi bir başlangıç istemi içerir ve ödeme kabul eden uygulamalar için mağaza şablonları iyi bir başlangıç noktasıdır.

Sorular