Shopify webhook'larıyla sipariş taşırken kayıp ve çift kayıt nasıl önlenir? Beş saniye kuralı, HMAC doğrulama, idempotency, yeniden deneme ve izleme kontrol listesi.
Shopify'dan ERP'ye, kargo sistemine ya da pazaryeri paneline sipariş taşıyan entegrasyonların çoğu webhook'a dayanır. Webhook'un nasıl çalıştığını bilmezseniz iki sorunla karşılaşırsınız: kaybolan siparişler ve iki kez kaydedilen siparişler. Bu yazıda Shopify'ın resmî dokümanlarına dayanarak webhook'u güvenli, tekrarlara dayanıklı ve izlenebilir kurmanın yolunu anlatıyoruz.
Webhook nedir, neden sipariş entegrasyonunun omurgasıdır?
Webhook, mağazada bir olay olduğunda (sipariş oluştu, ürün güncellendi, stok değişti) Shopify'ın sizin belirlediğiniz adrese HTTP isteği göndermesidir. Alternatif, entegrasyonun sürekli "yeni sipariş var mı?" diye sormasıdır. Webhook gecikmeyi azaltır ve gereksiz sorguyu ortadan kaldırır. API, webhook, dosya ve RPA arasındaki seçimi API entegrasyonları yazımızda ele almıştık; burada webhook'u seçtiğinizi varsayıp işin sağlamlık tarafına odaklanıyoruz.
Webhook bir garanti değil, bir bildirimdir. Shopify tekrarları en aza indirmeye çalışır; ancak alıcı sisteminiz kapalıysa, yavaşsa veya hata veriyorsa bildirim size ulaşmayabilir. Tasarımınız bunu baştan varsaymalıdır.
Beş saniye kuralı: önce yanıt verin, sonra işleyin
Shopify dokümanına göre uygulamanız webhook'a beş saniye içinde yanıt vermelidir; bağlantı için ayrıca bir saniyelik zaman aşımı vardır. Yanıt gelmezse teslimat başarısız sayılır. 200 dışındaki her yanıt, 3XX yönlendirmeler dahil, hata olarak değerlendirilir. Doküman bu yüzden işlemi yanıttan sonraya bırakmanızı önerir.
Pratikte şu akış kurulur:
- İstek gelir, imza doğrulanır.
- Ham veri bir kuyruğa ya da veritabanı tablosuna yazılır.
- Hemen 200 döndürülür.
- Asıl iş (ERP'ye sipariş yazma, kargo kaydı açma) kuyruktan ayrı bir süreçte yapılır.
ERP çağrısı yavaş olduğu için webhook yanıtını bekleten entegrasyonlar, trafiğin yoğun olduğu kampanya günlerinde zaman aşımına düşer ve sorun tam o anda büyür.
Kuyruk kullanmak ayrıca size sıra ve hız kontrolü verir: hedef sistem yavaşladığında kayıtlar kaybolmaz, bekler; hedef sistem toparlandığında kontrollü hızda işlenir. Kuyruğa yazmadan 200 dönmek ise tersine bir risk yaratır, bu yüzden yanıtı yalnızca kayıt kalıcı biçimde saklandıktan sonra verin.
Gelen isteği doğrulayın: HMAC imzası
Adresiniz internete açıktır; herkes oraya sahte sipariş gönderebilir. Shopify bu yüzden her istekte X-Shopify-Hmac-SHA256 başlığı gönderir. Bu, uygulamanızın istemci gizli anahtarı (client secret) ve ham istek gövdesiyle üretilmiş, base64 kodlu bir imzadır. Doğrulama için gövdeden aynı yöntemle HMAC-SHA256 hesaplar ve başlıktaki değerle karşılaştırırsınız; uyuşmayan teslimatı reddedersiniz.
Dikkat edilecek üç nokta var:
- Doğrulama ham gövdeyle yapılır. Gövde önce JSON'a çevrilip yeniden yazılırsa imza tutmaz; doğrulamayı gövde ayrıştıran ara katmanlardan önce yapın.
- Karşılaştırmayı zamanlama saldırılarına dayanıklı bir fonksiyonla yapın (Shopify'ın Node örneği
crypto.timingSafeEqualkullanır). - Gizli anahtarı yenilerseniz, dokümana göre yeni anahtarla imzalamanın başlaması bir saati bulabilir; bu sürede iki anahtarı da kabul etmek geçiş sorunlarını önler.
Tekrar eden teslimatlar: aynı sipariş iki kez gelirse
Shopify, tekrarları en aza indirdiğini ama uygulamanızın aynı webhook'u birden fazla kez alabileceğini açıkça söyler; örneğin ağ zaman aşımından sonra ya da yeniden denemede. Önerilen yaklaşım, işleminizi idempotent kurmaktır: aynı webhook iki kez gelse sonuç değişmemelidir.
Bunu sağlamanın pratik yolları:
- Sipariş kimliğini anahtar yapın: ERP'ye yazarken Shopify sipariş numarasını benzersiz referans olarak saklayın; aynı referans zaten varsa ikinci kaydı açmak yerine mevcut kaydı güncelleyin.
- Webhook kimliğini kaydedin: idempotent kurmak mümkün değilse, dokümanın önerdiği gibi X-Shopify-Webhook-Id başlığını kalıcı bir tabloya yazın; kimlik daha önce işlendiyse işlemi atlayıp başarılı yanıt döndürün.
- Başlıkları karıştırmayın: aynı konuya birden fazla abonelik varsa her birinin Webhook-Id'si farklı, X-Shopify-Event-Id'si ise ortaktır. Event-Id aynı olayın tekrarı değil, aynı mağaza işleminden doğan teslimatları ilişkilendirmek içindir.
Varsayımsal örnek: çift kayıt maliyeti
Günde 1.000 webhook aldığınızı ve bunların 8'inin tekrar geldiğini varsayalım. İdempotency yoksa her tekrar ikinci bir ERP kaydı, ikinci bir kargo etiketi ya da ikinci bir stok düşümü demektir. 8 çift kayıt günde, 30 günlük bir ayda 240 düzeltme işine döner (8 × 30). Aynı sistem sipariş numarasını benzersiz anahtar yaptığında bu 240 hatanın tamamı sıfıra iner. Rakamlar yalnızca mantığı göstermek için uydurulmuştur.
Yeniden deneme, silinen abonelik ve uzlaştırma
Yeniden deneme ve abonelik silinmesi
Teslimat başarısız olursa Shopify, dokümana göre en fazla sekiz kez ve dört saat içinde yeniden dener. Başarısızlık sürerse abonelik kaldırılır; doküman, Admin API ile oluşturulmuş aboneliklerde sekiz ardışık başarısızlıktan sonra otomatik silme olduğunu ve uygulamanın acil durum geliştirici e-postasına uyarı gönderildiğini belirtir. Silinen abonelik, siz yeniden oluşturana kadar hiç teslimat almaz. Yani webhook adresiniz bir hafta sonu boyunca bozuk kalırsa, hata düzeldiğinde bile yeni siparişler gelmeyebilir.
Yeniden denemelerle ilgili iki ayrıntı daha önemlidir:
- Yeniden denenen webhook, tetiklendiği andaki özgün veriyle gelir. Verinin eskimiş olup olmadığını X-Shopify-Triggered-At başlığına veya yük içindeki zaman damgasına bakarak anlayın; örneğin gecikmiş "sipariş güncellendi" olayı, daha yeni bir güncellemenin üstüne yazılmamalıdır.
- Yeniden deneme, tetiklendiği andaki adrese gider. Adresi taşıyorsanız Shopify'ın önerisi, geçiş sırasında iki adresi bir süre birlikte açık tutmaktır.
Uzlaştırma işi: kaçan olayı yakalayın
Shopify, yaygın bir uygulama olarak, kaçırmış olabileceğiniz veriyi Shopify API'leriyle periyodik olarak çeken bir uzlaştırma (reconciliation) işi kurmayı önerir. Kesinti sonrası toparlanma için de abonelikleri yeniden oluşturmanızı ve kesinti dönemindeki veriyi çekip webhook işleme kodunuzdan geçirmenizi söyler. Doküman, hangi API sorgusunun kullanılacağını belirtmez; bu sorgunun tasarımı sizin entegrasyonunuza bağlıdır.
Uzlaştırma işi basit tutulabilir: günde birkaç kez son saatlerdeki siparişleri API'den listeler, hedef sistemde karşılığı olmayanları işler. Aynı işleme kodunu kullandığınız için idempotency zaten çift kaydı engeller. Pazaryerleri ve ERP ile birlikte çalışan yapılarda webhook ile periyodik sorgunun birlikte kullanımını çok kanallı stok ve fiyat senkronizasyonu yazımızda da anlatmıştık.
İzleme ve alarm kontrol listesi
Webhook entegrasyonunun hatası sessizdir; kimse fark etmeden siparişler birikir. Dokümana göre başarısız teslimat oranının yüzde 0,5'in üzerine çıkması bir uyarı işaretidir. Şu kontrolleri kurun:
- Webhook adresiniz için dış kaynaklı canlılık kontrolü (uptime) ve hata alarmı ekleyin.
- Kuyrukta bekleyen kayıt sayısını ve en eski kaydın yaşını izleyin; belirli eşiği aşınca alarm verin.
- Geliştirici e-postasını (uygulamanın acil durum e-postası) izlenen bir ekip adresine yönlendirin, kişisel kutuya değil.
- Günlük bir karşılaştırma yapın: Shopify'daki sipariş sayısı ile hedef sistemdeki sayı eşleşiyor mu?
- Hatalı kayıtları silmek yerine "bekleyen hata" tablosunda tutun ve elle yeniden işlenebilir yapın.
- Abonelik listesini düzenli kontrol edin; beklediğiniz konuların hepsi hâlâ kayıtlı mı?
Kodsuz çözümle yetinen küçük mağazalar için bazı bildirim ve etiketleme işleri Shopify Flow ile yapılabilir; ancak ERP ve kargo gibi iki yönlü kayıtlarda yukarıdaki dayanıklılık kuralları özel entegrasyon katmanında aranmalıdır. Bu katmanı hazır entegratöre mi yaptıracağınız, yoksa özel API ile mi kuracağınız kararı için hazır entegratör mü, özel API mi yazımıza bakın.
Kesinti provası: entegrasyonu canlıya almadan önce deneyin
Webhook entegrasyonları, normal günde kusursuz çalışıp ilk kesintide sorun çıkarır. Bu yüzden canlıya almadan önce dört senaryoyu bilerek deneyin:
- Aynı olayı iki kez gönderin: test ortamında aynı sipariş yükünü art arda iki kez gönderin ve hedef sistemde tek kayıt oluştuğunu doğrulayın.
- İmzası bozuk istek gönderin: sistemin isteği reddettiğini ve kayıt oluşturmadığını görün.
- Hedef sistemi kapatın: ERP bağlantısını bilerek kesin; webhook'un yine hızlı yanıt verdiğini, kayıtların kuyrukta beklediğini ve bağlantı dönünce işlendiğini kontrol edin.
- Uzlaştırma işini çalıştırın: kuyruktan bilerek bir siparişi silin; uzlaştırma işinin bu eksiği bulup tamamladığını doğrulayın.
Bu dört deneme yarım gün sürer ve canlıda yaşanacak en pahalı hataların çoğunu önceden gösterir. Sonuçları kısa bir not olarak saklayın; entegrasyonu devralan ekip, neyin test edildiğini bilmek ister.
Entegrasyonu satın alırken veya yaptırırken sorulacak sorular
Entegrasyonu bir ajanstan ya da yazılım ekibinden alıyorsanız şu soruların yanıtını yazılı isteyin: İmza doğrulaması ham gövdeyle mi yapılıyor? Yanıt, işlemden önce mi dönüyor? Aynı sipariş iki kez gelirse ne oluyor? Üç günlük kesintiden sonra kaçan siparişler nasıl geri alınıyor? Hata alarmı kime gidiyor? Bu beş soruya net cevap veremeyen bir entegrasyon, kampanya haftasında ilk sınavında zorlanır.
Sonuç
Webhook'u güvenilir kılan şey, tek bir teknik hile değil, birbirini tamamlayan dört alışkanlıktır: beş saniye içinde yanıt verip işi kuyruğa bırakmak, imzayı ham gövdeyle doğrulamak, işlemi tekrara dayanıklı kurmak ve kaçanları periyodik bir uzlaştırma işiyle toplamak. Bunların üstüne basit bir izleme ve alarm düzeni eklerseniz sipariş entegrasyonunuz kampanya günlerinde de sessizce çalışmaya devam eder.
Kaynaklar: Shopify.dev, "Verify webhook deliveries" ve "Troubleshoot webhooks" sayfaları; Shopify.dev changelog, "Updates to webhook retry mechanism" (2026'da erişildi). Hesap örneği varsayımsaldır.