EntegrasyonE-ticaretERP 7 Kas 2026 · BenomCORE Ekibi

Webhook nedir? Sipariş ve fatura bildirimlerini güvenilir yönetme rehberi

Webhook’ların çalışma biçimini, yinelenen bildirimleri tekilleştirmeyi ve entegrasyon güvenliğini pratik adımlarla öğrenin.

Kısaca: Webhook, bir sistemde gerçekleşen olayı başka bir sisteme HTTP isteğiyle bildiren yöntemdir. Sürekli sorgulama yerine olay anında haber verir; güvenilir kullanım için göndereni doğrulayın, tekrarları tekilleştirin, hızlı yanıt verip işi kuyrukta yürütün ve başarısız bildirimleri izleyin.

Webhook nasıl çalışır?

Bir uygulama, belirlediğiniz HTTPS adresine olay oluştuğunda istek gönderir. Örneğin ödeme sağlayıcısı bir aboneliğin durumunun değiştiğini bildirebilir; mağaza ise yeni sipariş bilgisini operasyon sistemine iletebilir. Alıcı uç nokta isteği doğrular, olay kimliğini kaydeder ve gerekli işi başlatır.

Webhook ile düzenli sorgulama arasındaki temel fark zamanlamadır. Sorgulamada alıcı belirli aralıklarla “yeni kayıt var mı?” diye sorar. Webhook'ta gönderen, olay olduğunda haber verir. Bu gecikmeyi ve gereksiz istekleri azaltabilir; ancak bildirimin yalnızca bir kez ulaşacağını varsaymamak gerekir.

Aynı bildirim neden tekrar gelebilir?

Gönderen sistem, alıcının yanıtını alamazsa aynı olayı yeniden gönderebilir. İlk istek işlenmiş fakat yanıt ağda kaybolmuş olabilir. Bu nedenle ikinci bildirim siparişte yeniden stok düşürmemeli veya aynı faturayı tekrar oluşturmamalıdır.

Olay kimliğini ya da işleme özgü kararlı bir anahtarı veritabanında benzersiz tutun. Önce bu anahtarı atomik biçimde kaydedin; kayıt zaten varsa olayın daha önce işlendiğini anlayıp yan etkiyi tekrarlamayın. Stripe'ın idempotency rehberi de yeniden denenen API isteklerinin aynı işlemi çoğaltmaması için anahtar kullanımını açıklar.

Örneğin `order.paid` olayı geldiğinde sipariş numarası ve olay türü bir işlem kaydıyla eşleşebilir. Aynı bildirim tekrar gelirse sistem mevcut kaydı bulur; stok hareketi ikinci kez oluşmaz. Anahtarın kapsamı ve saklama süresi iş gereksinimine göre tasarlanmalıdır.

Webhook güvenliği nasıl sağlanır?

İnternetten erişilebilir bir adres, gelen her isteğin güvenilir olduğu anlamına gelmez. Sağlayıcının imza doğrulama mekanizmasını kullanın; imza doğrulanmadan sipariş, ödeme veya yetki değiştiren işlem yapmayın. Sağlayıcının güncel kütüphane ve tekrar saldırısı önleme yönergelerini izleyin.

  • Üretimde HTTPS kullanın ve yalnız beklenen HTTP yöntemini kabul edin.
  • İmzayı, sağlayıcının tarif ettiği biçimde ve ham istek gövdesinde doğrulayın.
  • Olay türü, hesap ve kaynak kimliğinin beklenen akışa ait olduğunu denetleyin.
  • Gövdedeki veriyi doğrulayın; alan türü, uzunluğu ve değer sınırlarını kontrol edin.
  • Gizli anahtarları kaynak koduna koymayın; erişimini sınırlandırın ve güvenli yapılandırmada tutun.
  • Günlüklerde ödeme veya kişisel veriyi gereksiz yere saklamayın.

OWASP API Security Top 10; nesne ve işlev düzeyinde yetkilendirme, kimlik doğrulama, kaynak tüketimi ve güvenli olmayan üçüncü taraf API tüketimini ayrı riskler olarak tanımlar. Webhook da API yüzeyinin parçasıdır; tek başına güvenlik kontrolü sayılmaz.

Hızlı yanıt ve kuyruk nasıl tasarlanır?

Gönderenler genellikle alıcıdan kısa sürede başarılı HTTP yanıtı bekler. Ağır işi istek içinde bitirmeye çalışmak zaman aşımı ve yeniden teslimat riskini artırır. İsteği doğrulayın, olayın kalıcı kuyruğa alındığından emin olun, sonra yanıt verin; arka plan çalışanı işin kendisini yürütür.

Kuyruğa yazma ile başarı yanıtı arasında tutarlılık kurun. Veritabanı işlemi tamamlanmadan 2xx yanıtı vermek olayın kaybolmasına yol açabilir. Geçici hatalarda sağlayıcının tekrar deneme davranışını öğrenin; kalıcı hataları aynı biçimde süresiz tekrar etmeyin.

İşletim sırasında şu göstergeleri izleyin:

  • Alınan olay sayısı ve olay türleri.
  • İmza doğrulama hataları ve HTTP yanıt kodları.
  • Kuyrukta bekleme ve işin tamamlanma süresi.
  • Yinelenen olay oranı ve başarısız iş kuyruğundaki kayıtlar.
  • Yeniden oynatma işleminin zamanı ve sorumlusu.

Yeniden oynatma aracı aynı tekilleştirme kurallarını kullanmalıdır. Operasyon ekibi hangi olayın tekrar işlendiğini görebilmeli; günlüklerde gizli anahtar bulunmamalıdır.

Sipariş ve stok akışında nelere dikkat edilmeli?

Sipariş, ödeme, stok ve fatura farklı uygulamalardaysa hangi sistemin “asıl kayıt” olduğunu belirleyin. Pazaryerinden gelen siparişte stok güncellemesi, iptal ve iade olaylarının sırası ayrıca tanımlanmalıdır. Geç gelen eski bildirim yeni durumu geri çevirmemelidir.

Olay zamanı, sürüm veya kaynak kaydın güncel durumuyla çelişki kontrolü kurun. Gerekirse webhook'u yalnızca “değişiklik oldu” sinyali olarak kullanıp yetkili API'den güncel kaydı okuyun. Böylece geciken ve sıra dışı ulaşan bildirimlerin etkisini azaltabilirsiniz.

BenomCORE, bulut tabanlı ERP, e-ticaret ve ön muhasebe süreçlerini tek platformda yönetmek için konumlanır; marka bilgisinde pazaryeri sipariş ve stok senkronu doğrulanmıştır. Entegrasyonunuzun hangi olayları kapsadığını, iptal/iade durumlarını ve hata izleme yöntemini netleştirin. BenomCORE'u 15 gün ücretsiz deneyin.

Uygulamaya geçmeden önce nasıl plan yapılır?

Webhook entegrasyonu geliştirmeye başlamadan önce olay sözlüğü çıkarın. Her olay için gönderen sistemi, alıcıyı, tetikleyici koşulu, zorunlu alanları ve beklenen iş etkisini yazın. “Sipariş değişti” ifadesi tek başına yeterli değildir: yeni sipariş, iptal, kısmi iade ve adres değişikliği farklı davranışlar gerektirebilir.

Her olay için şu soruları yanıtlayın:

  • Olayın benzersiz kimliği nedir ve aynı mantıksal işlemde sabit kalır mı?
  • Hangi sistem güncel durumu belirleyen kaynaktır?
  • İstek doğrulanamazsa veya gövde beklenmeyen biçimdeyse ne yapılır?
  • Alıcı geçici olarak kapalıysa gönderen ne kadar süre ve hangi aralıkla tekrar dener?
  • İş kuyruğundaki kayıt ne zaman tamamlanmış sayılır?
  • İnsan müdahalesi gereken olaylar hangi ekranda ve kime görünür?

Bu soruları yanıtlamak, canlıya geçişte belirsizliği azaltır. Özellikle para, stok ve erişim yetkisi etkileyen olaylarda tekrar çalıştırmanın sonuçlarını test ortamında doğrulayın. “Başarılı yanıt” ile “iş kuralı tamamlandı” durumlarının birbirinden farklı olabileceğini tasarım dokümanında belirtin.

Test ve hata ayıklama nasıl yapılır?

Tek bir başarılı örnek, dayanıklılığı kanıtlamaz. Aynı olayın art arda iki kez gelmesini, imzanın geçersiz olmasını, zorunlu alanın eksik kalmasını ve kuyruğun geçici olarak erişilememesini ayrı senaryolar olarak deneyin. Ayrıca eski bir olayın yeni olaydan sonra ulaşması durumunda kaydın geriye gitmediğini kontrol edin.

Test sırasında üretim anahtarlarını kullanmayın ve gerçek müşteri/ödeme verisini örnek gövdelere kopyalamayın. Sağlayıcının test modu veya sentetik örnekleri varsa bunlarla ilerleyin. Her senaryoda beklenen HTTP yanıtını, kalıcı kayıt sayısını ve oluşan iş etkisini kaydedin; böylece tekrarların gerçekten ayıklandığı kanıtlanır.

Canlı izleme için yalnız toplam istek sayısına bakmayın. Başarılı yanıtların yanı sıra kuyruk gecikmesi, tekrar oranı ve olay türüne göre hata dağılımı da önemlidir. Bir sağlayıcı olayları yeniden göndermeye başladığında artan tekrar oranı, uç noktanın hata verdiğini veya yanıt süresinin uzadığını erkenden gösterebilir. Uyarı eşiğini iş akışının tolere edebileceği gecikmeye göre belirleyin.

İşletme tarafında bir bildirim başarısız olduğunda kimin karar vereceği de önceden belirlenmelidir. Otomatik tekrar deneme uygun değilse olay inceleme kuyruğuna alınmalı; yetkili kişi kaynağın güncel durumunu kontrol edip kontrollü telafi yapmalıdır. Böylece teknik hata, fark edilmeden yanlış stok ya da ödeme kaydına dönüşmez.

Sık sorulan sorular

Webhook ile API aynı şey midir?

Hayır. API sistemlerin veri veya işlev alışverişi yapmasını sağlayan arayüzdür; webhook ise belirli olayları alıcıya bildirme yöntemidir. Webhook çoğunlukla HTTP API uç noktasını kullanır.

Webhook bildirimi tekrar gelirse ne yapılmalı?

Olay kimliğini veya kararlı bir işlem anahtarını benzersiz kayıt olarak tutun. Anahtar daha önce işlendiğini gösteriyorsa yan etkiyi ikinci kez çalıştırmayın.

Webhook uç noktası herkese açık olabilir mi?

İnternetten erişilebilir olması gerekebilir; ancak istek doğrulanmadan işleme alınmamalıdır. İmza doğrulaması, HTTPS, veri kontrolü ve oran sınırlama birlikte ele alınmalıdır.

Kaynaklar

← Tüm yazılar Bir fikrin mi var? İlet
Why BenomCORE?