Webhook denince çoğu satıcının aklına gelen şey basit bir haberdir: sipariş tamamlandı, karşı tarafa bir istek at, bitti. Panelde bir URL alanı, yanında bir kaydet düğmesi ve konu kapanır sanılır. Gerçekte giden webhook bir bildirim değil, senin sistemin ile bayinin sistemi arasındaki sözleşmedir; ve bu sözleşme tek taraflıdır, çünkü teslim garantisi sana aittir.
Bu yüzden "webhook çalışıyor" cümlesi ölçülebilir bir ifade değildir. Karşı taraf 500 dönerse ne oluyor? Aynı sipariş iki kez bildirildiğinde bayi iki kez mi işliyor? İnternet kesintisinde biriken olaylar nereye yazılıyor? Bu soruların cevabı yoksa senin e-pin satış scripti bayilerine güvenilmez bir veri kaynağı olur ve kurumsal müşteri ilk ayda seni bırakır. Aşağıda giden webhook katmanının bir işletme için nasıl kurulması gerektiğini, panel tarafında neyin bulunması gerektiğine kadar açıyoruz.
Webhook'u "Bildirim" Sanmak Seni Neden Yanıltıyor?
Bildirim tek yönlüdür ve kaybolabilir; webhook ise karşı tarafta iş tetikleyen bir tetikleyicidir. Bayinin stok düşmesi, muhasebe kaydı ya da son kullanıcıya kod iletimi senin gönderdiğin bu isteğe bağlıysa, bir kayıp doğrudan maddi sonuç doğurur. Dolayısıyla webhook katmanını e-posta gibi değil, sipariş kuyruğu gibi tasarlamak gerekir.
Bunun pratik karşılığı şudur: olay üretildiği anda veritabanına yazılır, ayrı bir arka plan işçisi tarafından gönderilir, sonucu kaydedilir ve başarısızsa tekrar denenir. Gönderimi doğrudan sipariş akışının içinde yapmak en yaygın hatadır; karşı taraf yavaş cevap verdiğinde senin sipariş sayfası da yavaşlar ve müşteri ödeme ekranında bekler. Üretim ile gönderimi ayırmak, iyi bir dijital ürün satış scripti ile kötüsü arasındaki ilk farktır.
Aynı Olay Neden İki Kez Gidiyor ve Bu Bir Hata mı?
Hayır, bu tasarımın doğal sonucudur. Ağ dünyasında "en az bir kez teslim" gerçekçi hedeftir; "tam olarak bir kez" ise pratikte pahalıdır. Karşı taraf isteği aldı ama cevabı sana ulaşmadan bağlantı koptuysa, sen başarısız sayıp tekrar gönderirsin ve olay iki kez işlenmiş olur.
Çözüm alıcı tarafın tekrarı tanıyabilmesidir. Her olaya değişmeyen bir kimlik ver ve bunu hem gövdede hem başlıkta gönder: X-Event-Id. Bayinin sistemi bu kimliği kaydedip ikinci kez gördüğünde işlemi atlar. Dokümanında bunu açıkça yazmalısın, çünkü idempotency sorumluluğu paylaşılır: sen kimliği üretirsin, alıcı tekrarı süzer. Bu tek başlık, bayilerle yaşanan "çift teslim" tartışmalarının neredeyse tamamını ortadan kaldırır.
| Olay tipi | Ne zaman gönderilir | Kritik alanlar | Tekrar denenmeli mi |
|---|---|---|---|
| order.created | Sipariş kaydı oluştuğunda | order_id, tutar, ürün | Evet |
| order.paid | Ödeme onayı alındığında | order_id, ödeme yöntemi | Evet |
| order.delivered | Kod/lisans teslim edildiğinde | order_id, teslim zamanı | Evet |
| order.refunded | İade tamamlandığında | order_id, iade tutarı | Evet |
| stock.low | Eşik altına düşüldüğünde | ürün, kalan adet | Hayır |
| balance.updated | Bayi bakiyesi değiştiğinde | bayi_id, yeni bakiye | Evet |
Alıcı Sunucu Kapalıysa Olayın Nereye Gidiyor?
Hiçbir yere gitmiyorsa sorun sende. Bayinin sunucusu bakımda olabilir, SSL sertifikası düşebilir, DNS geçici bozulabilir. Bu durumlarda olayın kaybolmaması için kalıcı bir kuyruk ve artan aralıklı tekrar deneme politikası gerekir: 30 saniye, 2 dakika, 10 dakika, 1 saat, 6 saat gibi. Beşinci denemeden sonra olay "ölü mektup" durumuna alınır ve panelde manuel yeniden gönderim düğmesiyle beklemeye geçer.
Bir de devre kesici mantığı vardır: aynı hedefe üst üste çok sayıda hata alındıysa o hedefe gönderim geçici olarak durdurulur. Yoksa kapalı bir sunucuya binlerce istek denemek senin işçilerini tıkar ve sağlıklı bayilerin bildirimleri gecikir. Tek bir arızalı hedefin bütün kuyruğu rehin almasına izin verme.
Başarısız Giden Webhook Nedenleri
- Alıcıda zaman aşımı 40%
- Hatalı veya süresi geçmiş URL 28%
- SSL ve sertifika sorunları 20%
- İmza doğrulama reddi 12%
İmzasız Webhook Göndermek Müşterine Ne Kadar Zarar Verir?
İmzasız bir webhook, bayinin sistemine "bu isteği bana gerçekten sen mi gönderdin" sorusunu soramamak demektir. URL'yi bilen herkes sahte bir teslim bildirimi uydurabilir. Bu, bayinin stoğunu düşürmekten son kullanıcıya haksız kod vermeye kadar giden bir açıktır ve faturası sana yazılır.
Standart yöntem HMAC-SHA256 imzasıdır. Paylaşılan bir gizli anahtar ile ham gövdenin özeti hesaplanır ve X-Signature başlığında gönderilir. Yanına X-Timestamp ekle, alıcı beş dakikadan eski istekleri reddetsin; böylece kaydedilmiş bir isteğin sonradan tekrar oynatılması engellenir. İmzanın gövdenin ham hali üzerinden hesaplandığını dokümanına yaz, çünkü JSON'u yeniden kodlayan alıcılar imzayı tutturamaz ve destek talebi olarak sana geri döner. Böyle bir e-pin yazılımı kurgusunda her hedef için ayrı gizli anahtar tutulur ve anahtar panelden döndürülebilir.
Dokümanına şunu yaz: alıcı isteği alır almaz 200 dönmeli, ağır işlemi kendi kuyruğunda yapmalı. Senin tarafta 3 saniyelik zaman aşımı koy; böylece yavaş bir bayi bütün gönderim hattını yavaşlatmaz.
Sıralama Garantisi Yok mu? O Zaman Ne Yapmalısın?
Paralel çalışan işçiler ve farklı tekrar deneme zamanlamaları yüzünden olaylar hedefe üretildikleri sırayla ulaşmayabilir. Teslim bildirimi, ödeme bildiriminden önce düşebilir. Bayinin durum makinesi buna hazır değilse sipariş kaydı tutarsız hale gelir.
Ucuz ve etkili çözüm her olaya artan bir sıra numarası ve olay zamanı eklemektir. Alıcı, elindeki kayıttan daha eski bir olay geldiğinde onu yok sayar. Daha sıkı ihtiyaçlarda sipariş kimliği bazında tek işçi atanır, yani aynı siparişin olayları hep aynı sırada gider. Bir de şu iyi alışkanlık var: olay gövdesine kaynağın o andaki tam durumunu koy, sadece "değişti" demekle yetinme. Böylece sıra bozulsa bile alıcı en güncel resmi görür.
Giden Webhook'ları Nasıl Gözlemlenebilir Hale Getirirsin?
Panelde her hedef için bir gönderim geçmişi olmalı: olay tipi, deneme sayısı, HTTP durum kodu, yanıt gövdesinin ilk birkaç yüz karakteri ve süre. Bir bayi "bize hiç bildirim gelmedi" dediğinde bu ekran tartışmayı otuz saniyede bitirir. Yeniden gönder düğmesi, hedef bazlı başarı oranı ve son hata mesajı da aynı ekranda olmalı.
Bunun üstüne test gönderimi ve hedef doğrulama koy: URL kaydedilirken örnek bir olay gönderilip imza doğrulamasının çalıştığı teyit edilir. Pinova'nın giden webhook katmanı bu mantıkla kuruldu; kalıcı kuyruk, imzalı gövde, artan aralıklı tekrar deneme, devre kesici ve hedef bazlı log tek ekranda yönetilir. Yapıyı özellikler bölümünde inceleyebilir, paketleri fiyat sayfasında karşılaştırabilirsin. Bu disiplini kuran bir e-pin satış yazılımı, kurumsal bayi görüşmelerinde teknik itirazların çoğunu baştan kapatır.
| Kontrol | Beklenen değer | Nerede görülür | Önem |
|---|---|---|---|
| Olaylar kalıcı kuyruğa yazılıyor | Veritabanı tablosu | Webhook logları | Kritik |
| HMAC imza başlığı gönderiliyor | X-Signature | Gönderim detayı | Kritik |
| Zaman damgası başlığı var | X-Timestamp | Gönderim detayı | Kritik |
| Olay kimliği tekil | X-Event-Id | Olay kaydı | Kritik |
| Artan aralıklı tekrar deneme | 5 deneme | Hedef ayarları | Yüksek |
| Devre kesici eşiği tanımlı | 10 hata / 5 dk | Hedef ayarları | Yüksek |
| Manuel yeniden gönderim | Tek tuş | Log ekranı | Orta |
| Test gönderimi düğmesi | Mevcut | Hedef ekleme | Orta |
Bayilerine teslim garantisi verebilen bir altyapı kur
İmzalı gövde, kalıcı kuyruk, tekrar deneme ve hedef bazlı log hazır gelsin; sen entegrasyon değil satış konuş.
Webhook gönderimini sipariş akışının içinde yapsam olmaz mı?
Olmaz. Alıcı yavaş cevap verdiğinde senin sipariş sayfası da bekler. Olayı kuyruğa yaz, arka plan işçisiyle gönder; kullanıcı deneyimi karşı tarafın hızına bağlı kalmasın.
Aynı bildirimin iki kez gitmesini tamamen engelleyebilir miyim?
Pratikte hayır. Doğru yaklaşım her olaya tekil bir kimlik vermek ve alıcının bu kimliği kaydederek tekrarı atlamasını dokümanda şart koşmaktır.
İmza için hangi yöntemi kullanmalıyım?
HMAC-SHA256 yeterli ve yaygındır. Hedef başına ayrı gizli anahtar tut, gövdenin ham hali üzerinden hesapla ve zaman damgasıyla birlikte gönder.
Başarısız olaylar ne kadar süre saklanmalı?
En az 72 saat, tercihen 30 gün. Bayi itirazlarını çözmek ve manuel yeniden gönderim yapabilmek için gövde ve yanıt kaydının erişilebilir kalması gerekir.
Giden webhook, bayinin senin sistemine duyduğu güvenin ölçülebilir halidir; imzasız ve kuyruksuz bir kurulum bu güveni ilk kesintide harcar. Kendi panelinin bu testi geçip geçmediğini görmek için canlı demo üzerinden webhook hedefi ekle, test gönderimi yap ve log ekranındaki deneme geçmişini incele. Gördüğün ayrıntı seviyesi, kurumsal bir bayiyle masaya oturduğunda elindeki en güçlü cevap olacak.