Shopify Webhook ve Idempotency: Entegrasyon Güvenilir mi?

Sipariş ERP’ye iki kez düşüyor, stok yanlış güncelleniyor veya müşteriye mükerrer e-posta gidiyor — çoğu zaman sorun Shopify’da değil, webhook handler tasarımındadır. Shopify olayları “en az bir kez” iletir; aynı sipariş bildirimi birden fazla gelebilir. Idempotency olmadan entegrasyon güvenilir sayılmaz.

Bu yazı kimler için?

Mağaza sahibi: Özel entegrasyon veya ajans projesi yaptırıyorsunuz; “sistem güvenilir mi?” sorusuna teknik checklist istiyorsunuz.

Ajans / entegrasyon geliştiricisi: ERP, lojistik, baskı-on-demand veya CRM bağlantısı kuruyorsunuz; webhook mimarisini doğru kurmak zorundasınız.

Kurucu / ürün sahibi: Shopify app fikri var; arka plan işlemlerinin production’da nasıl davranması gerektiğini önceden bilmek istiyorsunuz.

Karar problemi: Entegrasyonunuz aynı olayı iki kez aldığında ne yapıyor? Cevap “bilmiyoruz” veya “henüz olmadı” ise risk taşıyorsunuz demektir.

Somut karar problemi

Webhook şu durumlarda gereklidir:

Sipariş oluşunca harici sisteme aktarım
Stok veya fiyat senkronizasyonu
Müşteri veya abonelik verisi güncelleme
Uygulama kaldırıldığında temizlik (app/uninstalled)

Polling (API’yi periyodik sorma) alternatif olabilir ama gecikme ve rate limit getirir; gerçek zamanlı operasyonlarda webhook tercih edilir. Webhook seçtiyseniz idempotency seçmiş olursunuz — kaçınılmazdır.

Tipik kırılma noktaları:

Handler 30 saniyede cevap veremiyor → Shopify retry tetikler → çift işlem
orders/updated, orders/create sırası karışıyor → eksik veya eski veri
HMAC doğrulaması yok → sahte istek riski
Geçici hata ile kalıcı hata aynı şekilde 5xx dönüyor → sonsuz retry veya veri kaybı

Karar çerçevesi ve kontrol listesi

Temel güvenlik

X-Shopify-Hmac-Sha256 ile raw body doğrulanıyor
Doğrulama başarısız istekler 401 ile reddediliyor

Idempotency (çift işlemeyi önleme)

X-Shopify-Webhook-Id veritabanında saklanıyor; daha önce görüldüyse 200 dönülüp işlem tekrarlanmıyor
Alternatif: topic + kaynak ID (ör. sipariş ID) kombinasyonu ile upsert
Harici API’ye giden isteklerde idempotency key kullanılıyor (destekliyorsa)

Performans ve retry

Handler hızlı 2xx dönüyor; ağır iş queue/worker’da
Geçici hatalarda 5xx (retry için); kalıcı hatalarda 2xx + log (sonsuz retry önleme)
Dead letter queue veya başarısız iş kuyruğu var

Sıralama toleransı

orders/create gelmeden orders/updated gelebilir senaryosu ele alınmış
Eski event timestamp’leri yeni veriyi ezemiyor
Eksik kaynak için erteleme veya yeniden deneme mantığı var

Gözlemlenebilirlik

Webhook başarı/hata metrikleri izleniyor
Test ortamında aynı payload’ın tekrar gönderimiyle idempotency test edildi

Pratik kural: Webhook ID tablosu + hızlı yanıt + async işleme üçlüsü olmadan production entegrasyonu tamamlanmış saymayın.

Webhook konularını nasıl seçersiniz?

Her Shopify olayı için webhook açmak gereksiz karmaşıklık yaratır. İhtiyacınıza göre minimum set:

Sipariş akışı → orders/create, gerekirse orders/updated veya orders/cancelled
Stok senkronu → inventory_levels/update veya products/update
Uygulama yaşam döngüsü → app/uninstalled
Abonelik tabanlı app → app_subscriptions/update

Her handler tek bir sorumluluğa sahip olmalı; “tek endpoint’te her şeyi yap” deseni test ve idempotency’yi zorlaştırır. Staging ortamında Shopify CLI webhook trigger veya Partner dashboard test gönderimi ile aynı payload’ı kasıtlı olarak tekrarlayın — production’a çıkmadan önce en değerli doğrulama budur.

Mağaza sahibi olarak ajansınıza şu soruyu sorun: “Aynı sipariş bildirimi iki kez gelirse sistem ne yapar?” Net, yazılı cevap yoksa entegrasyon henüz güvenilir kabul edilmemelidir.

Entegrasyon sözleşmesinde veya proje tesliminde idempotency test raporu isteyebilirsiniz: aynı webhook ID’sinin ikinci gelişinde işlem yapılmadığının kanıtı. Bu, “çalışıyor gibi görünüyor” ile “production’da güvenilir” arasındaki farkı netleştirir. Özellikle yüksek sipariş hacimli mağazalarda bu test atlanmamalıdır. Düşük hacimde bile retry davranışı aynıdır; idempotency erken kurulmalıdır.

Sık yapılan hatalar

“200 döndük, sorun yok” deyip idempotency atlamak. Retry sonrası aynı sipariş iki kez faturalandırılır veya kargoya iki kez düşer.

Senkron ağır işlem. ERP çağrısı handler içinde 45 saniye sürerse timeout ve tekrarlı teslimat kaçınılmazdır.

Webhook ID saklamadan yalnızca “sipariş var mı?” kontrolü. orders/updated ile orders/create farklı event’lerdir; yalnızca sipariş ID yetmeyebilir.

HMAC’i parse edilmiş JSON üzerinde hesaplamak. Doğrulama raw request body ile yapılmalıdır.

Test ortamında tek seferlik happy path. Aynı webhook’u kasıtlı olarak iki kez göndermeden idempotency kanıtlanmış olmaz.

Sık sorulan sorular

Webhook ID kayıtları ne kadar saklanmalı?

Shopify retry penceresi genelde 48 saat civarındadır. En az 72 saat saklama yaygın ve güvenli bir pratiktir. Uzun saklama disk maliyeti artırır; iş hacminize göre temizleme politikası yazın.

Queue olmadan idempotency yeterli mi?

Idempotency çift işlemeyi önler ama ağır işi senkron yapmak timeout ve retry riskini artırır. Queue ile birlikte kullanmak production için daha sağlam mimaridir.

Polling ile webhook arasında nasıl seçim yapılır?

Gerçek zamanlı sipariş/ stok akışı → webhook. Saatlik rapor veya düşük hacimli senkron → polling kabul edilebilir. Hibrit modellerde (webhook + periyodik reconciliation) veri tutarlılığı güçlenir.

Mevcut entegrasyonu nasıl denetlerim?

Son webhook loglarında aynı X-Shopify-Webhook-Id için birden fazla işlem kaydı var mı bakın. Handler süreleri 5 saniyeyi aşıyorsa async’e geçiş değerlendirin. HMAC ve idempotency test checklist’ini staging’de tekrarlayın.

Sonraki adım

Entegrasyon projenizde webhook ve idempotency henüz net değilse, mimariyi gözden geçirmek en ucuz sigortadır. info@murattanriover.com.tr adresine mevcut akışınızı (ERP, lojistik, özel app) kısaca yazabilirsiniz; güvenilirlik açısından eksik noktaları birlikte tarayabiliriz.