Webhook Nedir?
Webhook, bir sistemde sipariş oluşması ya da ödeme tamamlanması gibi bir olay gerçekleştiğinde olay bilgisini önceden kaydedilmiş bir adrese HTTP isteğiyle kendiliğinden gönderen bildirim yöntemidir.
Webhook Nasıl Çalışır?
Uygulama ilgilendiği olay türlerine abone olur ve bildirimin gönderileceği adresi kaydeder. Olay gerçekleştiğinde sağlayıcı olay bilgisini, çoğunlukla JSON biçiminde, bu adrese gönderir. Trendyol satıcı API’sinde sipariş paketleri için webhook kurulabilir; oluşturuldu, kargoya verildi, teslim edildi ve iade edildi gibi sipariş durumlarından hangilerinin bildirileceği seçilir, liste boş bırakılırsa bütün durumlar atanır.
API durum sorgulamada (polling) ise uygulama değişiklik olup olmadığını öğrenmek için API’ye düzenli aralıklarla istek gönderir. Shopify webhook’ları sürekli sorgulamaya göre daha verimli bir yol olarak tanımlar, ama webhook teslimatının her zaman güvence altında olmadığını da belirtir ve veriyi düzenli aralıklarla karşılaştıran mutabakat işleri önerir.
Webhook İmza Doğrulaması
Doğrulama yapılmazsa saldırgan, webhook adresine sahte olaylar göndererek sipariş hazırlama ya da kayıt değiştirme gibi işlemleri tetikleyebilir. Stripe her bildirimi Stripe-Signature başlığındaki bir imzayla, Shopify X-Shopify-Hmac-Sha256 başlığıyla gönderir; alıcı imzayı uç noktaya özel gizli anahtarla yeniden hesaplayıp karşılaştırır. Stripe imzaya bir zaman damgası da ekler; böylece ele geçirilip yeniden gönderilen eski bir bildirim reddedilebilir. İmza ham istek gövdesi üzerinden hesaplandığı için gövde değiştirilmeden doğrulanır.
Webhook Tekrar Teslimi ve Yinelenen Olaylar
Alıcı, bildirimi aldığını başarılı bir durum koduyla hemen bildirir; uzun işlemler yanıttan sonra bir kuyrukta yürütülür. Başarılı yanıt alamayan Stripe, canlı ortamda bildirimi üç güne kadar, giderek açılan aralıklarla yeniden dener. Bu yüzden aynı olay birden fazla kez gelebilir: Stripe işlenen olay kimliklerinin kaydedilmesini ve kayıtlı olayın yeniden işlenmemesini önerir; Shopify yinelenen teslimatların X-Shopify-Webhook-Id başlığıyla ayıklanabileceğini belirtir.
Webhook Olay Sıralaması
Stripe ve Shopify, olayların oluştukları sırayla teslim edileceğini güvence altına almaz. Shopify olayların X-Shopify-Triggered-At başlığına ya da yükteki updated_at zaman damgasına göre sıralanmasını önerir; Stripe eksik kalan nesnelerin API’den çekilebileceğini belirtir.
Örnek: Pazaryerinde sipariş kargoya verildiğinde ERP kaydı webhook ile güncellenir. Aynı bildirim iki kez gelir ve geciken oluşturuldu bildirimi kargoya verildi bildiriminden sonra ulaşır. Entegrasyon olay kimliğini kaydettiği için ikinci fatura oluşmaz; zaman damgasını karşılaştırdığı için eski durum yenisinin üzerine yazılmaz.
Webhook Hakkında Sık Sorulan Sorular
Webhook ile API arasındaki fark nedir?
API’de uygulama veriyi kendisi ister; webhook’ta ise sağlayıcı olay gerçekleşince veriyi uygulamaya kendiliğinden gönderir. Çoğu entegrasyon ikisini birlikte kullanır.
Webhook bildirimi kaybolursa ne olur?
Sağlayıcı başarısız teslimatı belirli bir süre yeniden dener. Bu süre içinde de teslim edilemeyen olaylar için uygulama veriyi API üzerinden düzenli olarak karşılaştırır.