Webhook nedir sorusu, ödeme ve kargo entegrasyonunda HTTP bildiriminin nasıl doğrulanacağıyla anlam kazanır. Bu rehber imza kontrolü, tekrar teslimat ve sıra dışı olayları adım adım ele alır. Amaç, sahte veya mükerrer isteğin sipariş kaydını bozmamasıdır.
Ödeme alındı, kargo yola çıktı veya iade onaylandı gibi olayları kendi sisteminize yazmak istiyorsanız önce net bir tanım gerekir: webhook nedir? Kaynak sistem, sizin açtığınız bir HTTP adresine istek atarak “bu olay gerçekleşti” haberini verir. Siz de o isteği okuyup sipariş, stok veya kargo kaydını güncellersiniz.
Bu yazı iç asenkron kuyruk kurmayı konu etmez. Asıl mesele, dış sistemden gelen bildirimin sahte olup olmadığını anlamak, aynı olayın iki kez gelmesini yönetmek ve geç kalan eski bir paketin güncel durumu ezmesini engellemektir. KepezWeb olarak e-ticaret ve özel yazılım işlerinde bu üç noktayı atlayan entegrasyonların sessizce yanlış sipariş ürettiğini görürüz.
Webhook nedir ve neden HTTP bildirimi kullanılır?
Kısa karşılık şudur: karşı taraf sizi periyodik olarak sorgulamaz; olay olunca sizi çağırır. Ödeme kuruluşu tahsilatı tamamladığında, kargo firması barkodu okuttuğunda veya pazaryeri siparişi iptal ettiğinde sizin endpoint’inize bir POST gelir.
Gövde çoğu zaman JSON’dur. Başlıklarda imza, olay tipi ve teslimat kimliği bulunur. Sizin işiniz bu isteği kabul etmek, doğrulamak ve kendi kaydınızı tutarlı hale getirmektir. Karşı tarafın sizi çekmesi, sizin onu sürekli sormanızdan daha az tur üretir; olay da daha çabuk ulaşır.
Karşılığında teslimat sizin kontrolünüzde değildir. İstek gecikebilir, iki kez gelebilir, eski bir olay yenisinden sonra düşebilir. Endpoint’i bir form işler gibi değil, güvenilmeyen bir sınır gibi tasarlamak gerekir.
Ödeme ve kargo bildirimlerinde asıl risk
Ödeme bildirimi yanlış işlenirse sipariş ödendi görünür ama tahsilat yoktur; ya da aynı tutar iki kez stok düşer. Kargo bildirimi yanlış işlenirse müşteriye teslim edildi gider, kurye hâlâ depodadır. Sorun genelde JSON okuyamamak değildir; sahte, mükerrer veya geç kalmış bir olayın iş kuralını çalıştırmasıdır.
Üç teknik risk tekrar eder:
- Kimlik: İsteği gerçekten ödeme veya kargo sağlayıcısı mı gönderdi?
- Tekrar: Aynı olay kimliği ikinci kez gelirse siparişi yeniden mi işleyeceksiniz?
- Sıra: “Kargoya verildi” olayı, “teslim edildi”den sonra gelirse durumu geri mi alacaksınız?
IP allowlist tek başına yetmez. Adresler değişebilir, paylaşılan altyapı devreye girebilir. Asıl kanıt, paylaşılan sırla üretilmiş imzadır. İmza yoksa gövdeye iş kuralı bağlamayın.
İmza doğrulama: gövdeyi okumadan önce
Gelen isteği hemen JSON’a çevirip siparişi güncellemeyin. Önce ham gövdeyi, ilgili başlığı ve sizin sakladığınız sırrı kullanarak imzayı doğrulayın. Gövdeyi parse edip yeniden yazmak anahtar sırasını değiştirir; imza o zaman rastgele kırılır veya yanlış kabul edilir.
- Ham gövdeyi olduğu gibi alın; yeniden serialize etmeyin.
- Sağlayıcının tarif ettiği kanonik metni kurun. Çoğu akışta gövde ve zaman damgası bu metne girer.
- HMAC veya sağlayıcının belirttiği algoritmayla imzayı hesaplayın.
- Sabit süreli karşılaştırma ile başlıktaki değerle denk bakın. Erken kırılan karşılaştırma zaman sızıntısı üretir.
- Zaman damgası sağlayıcının kabul ettiği pencerenin dışındaysa isteği reddedin. Kayıtlı geçerli bir paketin yeniden oynatılmasını keser.
Doğrulama başarısızsa 4xx dönün ve iş kuralı çalıştırmayın. Başarılı olsa bile gövdeye körü körüne güvenmeyin. Sipariş numarası sizin veritabanınızda var mı, tutar beklenen değerle uyuyor mu, para birimi değişmiş mi diye bakın. İmza kaynağı kanıtlar; iş kuralı tutarlılığı kanıtlamaz.
Sırrı uygulama koduna gömmeyin. Ortam değişkeni veya gizli deposu kullanın, rotasyonu planlayın. Canlı ve test sırrını ayırın. Log’a sırrı, ham imza başlığını ve kart verisini yazmayın. Adresi tahmin edilmesi zor bir yol yapmak ek katmandır; gizlilik imzanın yerini tutmaz. Sırrı query string’te taşımayın; HTTPS kullanın, çünkü URL log’a düşer.
Tekrar teslimat: aynı olayı ikinci kez işlemeyin
Dış sistem, sizin 2xx dönmediğinizi görünce aynı bildirimi yeniden gönderir. Ağ koptuğunda siz 200 vermiş olsanız bile paket karşı tarafta zaman aşımına düşmüş olabilir. Sonuç aynıdır: aynı olay iki veya üç kez gelir.
Güvenilir işleme, “bu olay daha önce işlendi mi?” sorusuna evet diyebilmektir. Anahtar sipariş numarası değil, sağlayıcının olay kimliği veya teslimat kimliğidir. Aynı siparişte meşru birden fazla olay vardır: yetkilendirme, yakalama, iade, kargoya veriliş, dağıtım, teslim.
- Her teslimatı olay kimliği ile kaydedin.
- Veritabanında benzersiz kısıt koyun; yarış durumunda ikinci yazma hata versin.
- İş kuralını bu kayıttan sonra, tek bir kez çalıştırın.
- İş zaten tamamsa yine 2xx dönün. Karşı taraf tekrar etmeyi kessin; siz ikinci kez stok veya tahsilat hareketi üretmeyin.
Ödeme örneği: ödeme başarılı bildirimi geldi. Olay kimliğini kaydedin, siparişi ödendi yapın, stok düşün. Aynı kimlik tekrar gelirse yalnızca “zaten işlendi” deyin. Yeni bir kimlikle gelen başarı bildirimi başka bir ödemedir; körü körüne yok saymayın, sipariş ve tutar eşleşmesini kontrol edin.
Kargo örneği: aynı “kargoya verildi” olayı iki kez gelirse ikinci kargo kaydı açmayın. Etiket, SMS veya stok hareketi bir kez üretilsin. İdempotent olmayan bir e-posta, müşteriye çift mesaj basar; bu da operasyonu değil, güveni bozar.
İki işçinin aynı anda aynı olay kimliğini işlemesi, “önce oku sonra yaz” ile kaçar. Benzersiz kısıt ihlalini “zaten var” kabul edip 2xx dönmek, tekrar teslimatı zararsız hale getirir.
Sıra dışı teslimat: eski olay yenisini ezmesin
Webhook’lar sıra garantisi vermez. “Dağıtıma çıktı” paketi ağda beklerken “teslim edildi” önce ulaşabilir. Siz teslim yazarsınız; geciken paket gelince durumu dağıtımda çekerseniz müşteri ve operasyon yanlış bilgi görür.
Çözüm, her gelen olayı mutlak doğru kabul edip üzerine yazmak değildir. Duruma bir sıra, zaman damgası veya durum makinesi uygulayın.
- Her olay tipine iş kuralı önceliği verin. Teslim, dağıtımdan sonra gelir. İade, teslimden sonra ayrı bir daldır.
- Kaynak sistem olay zamanı gönderiyorsa, elinizdeki kaydın zamanından eskiyse durumu düşürmeyin.
- Durum makinesi kullanın. Teslim edilmişken “kargoya verildi” geçişine izin vermeyin.
- Ödemede iade işlendikten sonra yetkilendirme ile durumu geri almayın.
Ödeme ve kargoda akış lineer olmayabilir. Kısmi iade, bölünmüş kargo, ikinci teslim denemesi gibi dallar vardır. Makineyi her sağlayıcı alan adına göre çizin; tek bir genel enum yetmez. “Ödendi / ödenmedi” iki hali, iade ve kısmi tahsilatı taşımaz.
Eksik kalan ara olay da olur. Teslim geldi, “kargoya verildi” hiç gelmedi. Teslimi kaydedin; eksik ara adımı uydurmayın. Operasyon ekranında “ara olay görülmedi” notu bırakmak, sahte bir kargo satırı üretmekten iyidir. Geç gelen ara olayı tarihçe olarak saklayın, güncel durumu geri almayın.
İmzayı doğrulamadan gövdeyi işlemeyin. Olay kimliği olmadan iş kuralını çalıştırmayın. Daha ileri bir durumu geriye çekmeyin.
Endpoint yanıtı, zaman aşımı ve hata ayrımı
Dış sistem sizin durum kodunuza bakarak tekrar eder. Doğrulama ve kayıt ile ağır iş kuralını ayırın. Amaç iç kuyruk ürünü kurmak değil; HTTP turunu kısa ve öngörülebilir tutmaktır.
- İmza yanlışsa 401 veya 400 dönün. Bu isteği tekrar etmek işe yaramaz.
- Geçici veritabanı hatasında 5xx dönün ki kaynak yeniden denesin.
- Kalıcı iş kuralı hatasında (bilinmeyen sipariş, tutar uyuşmazlığı) 4xx ve alarm üretin. Kör tekrar, bozuk kaydı çoğaltmasın.
- Yanıt gövdesini sade tutun. İç hata izini, şema ayrıntısını ve müşteri verisini sızdırmayın.
Endpoint uzun süren e-posta, etiket basımı veya başka bir dış API çağrısı yaparsa kaynak tarafı keser ve aynı olayı yeniden gönderir. İmza kontrolü ile idempotent kaydı hızlı tutun. Ağır yan etkiyi bildirimi kabul ettikten sonra, ayrı bir işlemde yürütün.
Sizin tarafınızda son başarılı teslimat, son hata ve işlenmemiş olay görünür olsun. Kör uygulama log’u, ödeme veya kargo takıldığında operasyonun bakacağı kayıt değildir. Geliştirme ortamında gerçek ödeme veya kargo webhook’unu açmayın. Ayrı URL, ayrı sır, ayrı sipariş öneki kullanın. Canlı sır test isteğiyle sızmasın. Bu ayrım, yazılım geliştirme işinde sınır netliği kadar sır netliği de ister.
Ödeme ve kargo için kontrol listesi
Aşağıdaki tablo, dış bildirimi “geldikten sonra ne oldu?” diye değil, “gelmeden önce ne kırılır?” diye okur.
| Sorun | Belirti | Ne yapmalısınız |
|---|---|---|
| Sahte istek | İmzasız veya bozuk imzalı gövde | Ham gövdeyle imzayı doğrulayın, sırrı döndürün |
| Çift işleme | Stok iki kez düşer, SMS iki kez gider | Olay kimliği ile tekil kayıt tutun |
| Eski olay | Teslim sonrası kargoda görünür | Durum makinesi ve olay zamanı uygulayın |
| Geç yanıt | Kaynak sürekli tekrar eder | Hızlı 2xx verin, ağır işi ayırın |
| Sessiz uyuşmazlık | Tutar veya para birimi kayıttan farklı | İş kuralını imzadan sonra doğrulayın |
Günlük işletim için kısa liste:
- Sır rotasyonu ve erişim kaydı
- Olay kimliği üzerinde benzersiz indeks
- Ödeme ve kargo için ayrı durum geçiş tablosu
- 4xx / 5xx ayrımı ve alarm
- Test ve canlı endpoint ayrımı
E-ticaret tarafında ödeme bildirimi, checkout sonrası “sipariş alındı ama ödeme belirsiz” boşluğunu kapatır. Bu boşluk kullanıcıda sürtünme de üretir. Ödeme ekranını sade tutmak ayrı bir iştir; e-ticaret checkout sürtünmesi yazısında form ve hata akışına bakabilirsiniz.
Sipariş, ödeme ve kargo kayıtlarını aynı özel yazılımda tutuyorsanız endpoint’i de o modele göre kurun. KepezWeb, e-ticaret sitesi işlerinde bildirimi ekran süsü değil, sipariş gerçeğinin kaynağı olarak ele alır.
Sıkça Sorulan Sorular
Webhook nedir, API çağrısından farkı nedir?
API’de siz karşı tarafı çağırırsınız. Webhook’ta karşı taraf, olay olunca sizin URL’nize HTTP isteği gönderir. Sorgulama periyodunuz yoktur. Güvenlik, tekrar ve sıra yönetimi size kalır.
Yalnızca IP kısıtı yeterli mi?
Hayır. Adres değişebilir, paylaşılan altyapı kullanılabilir. İmza, isteğin gövdesinin sizin sırrınızla üretildiğini gösterir. IP kısıtı ek katman olabilir, tek kanıt olamaz.
Aynı ödeme bildirimi iki kez gelirse ne yapmalıyım?
Olay kimliğini kaydetmiyorsanız stok, e-posta veya muhasebe fişi iki kez üretilir. Kayıt varsa ikinci istek 2xx ile biter, iş kuralı çalışmaz. Anahtar sipariş numarası değil, olay kimliğidir.
Kargo olayı sırasız gelirse siparişi geri almalı mıyım?
Hayır. Daha ileri bir durumdayken geriye çekmeyin. Eski olayı tarihçeye yazın ama güncel durumu düşürmeyin. Eksik ara olayı uydurmayın.
Webhook endpoint’i ne zaman 5xx dönmeli?
Geçici altyapı hatasında. İmza bozukluğu, bilinmeyen sipariş veya tutar uyuşmazlığında 4xx ve inceleme kaydı daha doğrudur. Aksi halde kaynak, bozuk isteği tekrar tekrar gönderir.
Ödeme ve kargo bildirimlerini mevcut sipariş modelinize göre tasarlamanız gerekiyorsa KepezWeb ekibine yazabilirsiniz. Entegrasyon ihtiyacını netleştirmek için teklif alın sayfasından hedefi ve mevcut sistemi iletmeniz yeterlidir. Böylece endpoint, imza ve durum geçişleri iş kaydınıza uygun planlanır.
