Webhook
Webhook, bir ödemenin başarılı olması gibi belirli bir olay gerçekleştiğinde bir uygulamanın sizin sağladığınız bir URL'ye otomatik olarak gönderdiği HTTP isteğidir; böylece diğer sistemler, tekrar tekrar sormadan değişikliklerden neredeyse gerçek zamanlı olarak haberdar olur.
Webhook nedir?
Sıklıkla ters API (reverse API) olarak adlandırılır: sisteminizin güncellemeleri sorması yerine, bir şey değiştiğinde diğer sistem sizi çağırır. Akış dört adımdan oluşur:
Bir HTTPS endpoint'i kaydeder ve Stripe'ın invoice.payment_failed veya Shopify'ın orders/create olayı gibi olay türlerini seçersiniz.
Olay, sağlayıcının sisteminde gerçekleşir.
Sağlayıcı; olay türü, olay kimliği, zaman damgası ve etkilenen nesneyi içeren JSON payload'u ile bir POST isteği gönderir.
Endpoint'iniz hızla 2xx durum koduyla yanıt verir; vermezse çoğu sağlayıcı bir geri çekilme (backoff) planına göre yeniden dener.
Teslimat genellikle "en az bir kez" (at least once) esasına dayanır; bu nedenle aynı olay iki kez gelebilir ve olaylar sırasız ulaşabilir. Bazı sağlayıcılar yalnızca bir olay kimliği gönderir ve tam nesneyi kendi API'leri üzerinden çekmenizi bekler; bu da güncelliğini yitirmiş verilere göre işlem yapmaya karşı koruma sağlar.
Güvenli ve güvenilir bir endpoint nasıl çalıştırılır?
Gelen her çağrıyı, imzası doğrulanana kadar güvenilmez kabul edin ve ilk günden itibaren yinelenen olaylara göre tasarlayın.
İmzaları doğrulayın: sağlayıcılar ham gövdeyi paylaşılan bir gizli anahtarla, genellikle HMAC-SHA256 ile imzalar ve imzayı Stripe-Signature veya X-Shopify-Hmac-Sha256 gibi bir header'da gönderir.
Tekrar oynatma (replay) saldırılarını engellemek için eski zaman damgalarını reddedin; Stripe'ın kütüphaneleri varsayılan olarak beş dakikalık bir tolerans kullanır.
Hızlı onaylayın, sonra işleyin: olayı Amazon SQS gibi bir kuyruğa koyun ve hemen 200 döndürün.
İşlemeyi idempotent yapın: olay kimliklerini saklayın ve zaten işlenmiş olanları atlayın.
Mutabakat yapın: zamanlanmış bir iş, kaçırılan her şeyi yakalamak için son kayıtları API üzerinden çeker.
Bir webhook entegrasyonu pratikte nasıl görünür?
Tipik bir entegrasyon, bir faturalama olayını saniyeler içinde birden fazla araçta aksiyonlara dönüştürür. Başarısız ödemelerin bir sonraki teslimat paketlenmeden önce ele alınmasını isteyen, abonelik usulü yemek kiti satan bir şirket düşünün.
Stripe, invoice.payment_failed olayını API Gateway arkasındaki bir AWS Lambda fonksiyonuna gönderir.
Fonksiyon imzayı doğrular, olayı SQS'e yazar ve 200 döndürür.
Bir worker, sipariş karşılama sistemindeki bir sonraki kutuyu duraklatır, HubSpot'taki müşteri kaydını günceller ve Klaviyo'da ödeme bilgisi güncelleme e-postasını tetikler.
Gecelik bir iş, günün başarısız faturalarını Stripe API üzerinden listeler ve callback'lerin kaçırdıklarını işler.
Diyelim ki daha önce kartı reddedilen bir müşteriye haftada yaklaşık bir kez kutu gönderiliyordu; bu akışla duraklatma, paketleme başlamadan önce gerçekleşir.
Webhook'larla ilgili yaygın tuzaklar nelerdir?
Olayların çoğu, endpoint ayaktayken her olayın tam olarak bir kez ve sırayla geldiğini varsaymaktan kaynaklanır. Tipik hatalar:
Yanıt vermeden önce yavaş işler yapmak; bu durumda sağlayıcı zaman aşımına uğrar, yeniden dener ve yinelenen olaylar oluşturur.
Sağlayıcının yeniden deneme penceresinden daha uzun süren bir kesinti sırasında olayları kaçırmak.
İmza kontrollerini atlamak; bu, URL'yi bulan herkesin sahte olay enjekte etmesine izin verir.
Bir sağlayıcı yeni bir API sürümü yayımladığında payload'un değişmesi.
Yerel testler için Stripe CLI, ngrok ve webhook.site gerçek payload'ları incelemenize olanak tanır. Bir sağlayıcı olay sunmadığında, tam bir durum senkronizasyonuna ihtiyaç duyduğunuzda veya veriler yalnızca günde bir kez önem taşıdığında yoklama (polling) daha iyi bir tercihtir.
Webhook, bir API'yi yoklamaktan (polling) nasıl ayrılır?
Yoklama (polling) belirli bir programla "yeni bir şey var mı?" diye sorar; olay callback'leri ise değişikliği gerçekleştiği anda iletir. Push yöntemi daha hızlıdır ve API kotalarını daha az tüketir; yoklama ise mantık olarak daha basittir ve bir sonraki kontrolde hâlâ mevcut olan hiçbir değişikliği kaçırmaz.
No-code araçlar olay almayı kolaylaştırır: Zapier'in Catch Hook tetikleyicisi, n8n Webhook node'u ve Make'in özel tetikleyicileri. Kendi müşterilerine olay gönderen ekipler için Svix ve Hookdeck; imzalama, yeniden denemeler ve teslimat loglarını yönetir. Bu kalıplar API entegrasyonunun, iPaaS platformlarının ve akış verisi üzerine kurulu gerçek zamanlı pipeline'ların bir parçasıdır.
Webhook'lar ve API yoklaması (polling)
Webhook'lar (push) | API yoklaması (pull) | |
|---|---|---|
Çağrıyı kim başlatır | Sağlayıcı, bir olay gerçekleştiğinde | Sisteminiz, belirli bir programla |
Gecikme | Saniyeler | Yoklama aralığına kadar |
API kotası kullanımı | Düşük | Sık yoklama yapılıyorsa yüksek |
Kaçırılan değişiklikler | Kesintiler sırasında mümkün | Her yoklama tam durumu okuyorsa nadir |
Ana iş yükü | İmzalar, yeniden denemeler, idempotency | Zamanlama, sayfalama, değişiklik tespiti |
VIZIO AI olay güdümlü entegrasyonları nasıl kullanır?
VIZIO AI, panellerin ve ekiplerin değişiklikleri manuel yenileme olmadan görmesi için canlı veri bağlantıları kurar. Minnesota merkezli bir mobilya ve aydınlatma şirketi için DX Studio, Shopify'dan ve dahili sistemlerden gelen canlı verileri işlemek için AWS Lambda fonksiyonlarını kullandı; 4K bir operasyon paneli için kimlik doğrulama ve gerçek zamanlı veritabanı güncellemelerini Firebase üstlendi.
Vaka çalışması, Shopify olaylarının push ile mi yoksa zamanlanmış çekmelerle mi geldiğini belirtmiyor; ortak nokta, serverless ve olay işleme odaklı tasarımdır. Operasyonel veri görünürlüğü %85, operasyonel verimlilik ise %21 arttı. Nereden başlamalı: işinizde saatlerce gecikmenin para kaybına yol açtığı üç olayı listeleyin ve her kaynak sistemin bunları push edip edemediğini kontrol edin.