Shopify Webhook Entegrasyonu: Kuyruk ve Hata Yönetimi

Teslim alma ile işleme aynı şey değildir

Bir sipariş olayı geldiğinde ERP bağlantısını çağırıp yanıtını bekleyen tek parça bir uç nokta kurmak cazip görünebilir. Ancak dış servis yavaşladığında hem olayın teslim alınması hem işin tamamlanması aynı gecikmeye bağlanır. Önerilen yaklaşım, doğrulanmış mesajı kalıcı bir iş kaydına almak ve dış sistem işlemini ayrı çalışan bir süreçte yürütmektir.

Başarılı HTTP yanıtını işin tamamlandığına dair müşteri mesajıyla karıştırmayın. Yanıt, mesajın güvenle kabul edildiğini ifade edebilir; sipariş aktarımı daha sonra tamamlanır. Yönetim panelinde “alındı”, “işleniyor”, “tamamlandı” ve “inceleme gerekiyor” durumlarını ayrı göstermek, operasyon ekibinin gerçeği görmesini sağlar.

İmza kontrolünü iş mantığından önce yapın

Shopify HTTPS webhook imzasını ham istek gövdesi ve uygulamanın istemci sırrı üzerinden üretir. JSON verisini yeniden biçimlendirip sonra imza hesaplamak aynı baytları kullanmayacağı için doğrulamayı bozabilir. Resmî dokümantasyon doğrulamanın yük içeriğine güvenmeden önce yapılmasını açıklar. [1]

Uygulamada ham gövdenin hangi ara katmanda okunduğunu belgeleyin. Yanlış imza, boş imza ve bozulmuş gövde testleri bulunsun. Gizli anahtarı hata mesajına veya kayıt sistemine yazmayın. İmzanın doğru olması da olaydaki her değerin iş kurallarınıza uygun olduğu anlamına gelmez; mağaza, kaynak ve beklenen veri türleri ayrıca doğrulanmalıdır.

Tekrarları iki ayrı seviyede düşünün

Aynı teslimatın tekrar gelmesi ile aynı iş olayının farklı teslimatlar üzerinden ulaşması birbirinden ayrılmalıdır. Shopify doğrulama rehberi, tekrarları belirlemek için teslimat kimliği kullanımını da ele alır. [1] İş sisteminde ayrıca siparişin dış sistem kimliğini kararlı tutmak, tekrar denemenin ikinci sipariş açmasını engellemek için kullanılabilir.

Örnek tasarımda gelen mesaj kimliğini kayıt tablosunda benzersiz tutun; hedef ERP siparişi için de mağaza ve sipariş kimliğinden bir iş anahtarı üretin. Mesajı alındı diye işaretlemekle hedef işlemi tamamlandı diye işaretlemeyi farklı alanlarda tutun. Böylece yarıda kalan çalışma kaybolmadan yeniden ele alınabilir.

Örnek: ERP kaydetti, yanıt yolda kayboldu

Varsayımsal akışta ERP siparişi oluşturuyor fakat bağlantı kesiliyor. Entegrasyon yalnızca zaman aşımı gördüğü için siparişin oluşmadığını varsaymamalıdır. Önce kararlı dış referansla hedef sistemde sorgulama yapılabilir. Kayıt bulunursa mevcut kimlik eşleştirilir; bulunmazsa kontrollü tekrar planlanır. Hedef sistemin sorgulama ve benzersizlik desteği bu kararın belirleyicisidir.

Sıra ve sürüm değişikliklerini yönetin

Eski bir durumun sonradan gelmesi yeni durumu geriye çekmemelidir. Olay zamanını, kayıt sürümünü veya gerektiğinde Shopify’dan yeniden okunan güncel kaydı kullanacak bir strateji belirleyin. “Her gelen mesaj son doğrudur” yaklaşımı özellikle kargo ve iptal akışlarında hatalı sonuç üretebilir. Buradaki çözüm projeye göre seçilmelidir; tek zaman damgası her çakışmayı çözmez.

Webhook abonelikleri sürümlenir; abonelik konusu ve gerekli erişim kapsamları birlikte değerlendirilir. Sürüm güncellemesini yalnızca yapılandırma satırını değiştirmek olarak görmeyin. Örnek mesajlarla sözleşme testi yapın ve tüketici kodunun alan değişikliklerine nasıl davranacağını kontrol edin. [2]

Hata kuyruğu operasyon ekibine ne göstermeli?

Kuyrukta mağaza, işlem referansı, hata sınıfı, deneme sayısı ve son işlem zamanı bulunabilir. Gereksiz kişisel veriyi kopyalamayın. Geçici bağlantı sorunu ile geçersiz ürün kodu aynı tekrar politikasına tabi olmamalıdır. Ürün kodu düzelmeden yüzlerce kez denemek çözüm üretmez; daha çok gürültü oluşturur.

Günlük uzlaştırma, yalnızca hata kuyruğuna düşen olaylara bakmaktan farklıdır. Shopify’daki ilgili siparişler ile hedef sistemdeki eşleştirmeleri karşılaştıran bir kontrol, görünmeyen eksikleri araştırmaya yardımcı olur. Bu kontrolün kapsamı, sıklığı ve sorumlusu teklifin parçası olmalıdır.

Sık sorulan sorular

### Webhook kullanmak zamanlanmış kontrolü gereksiz kılar mı? Hayır. Olay akışı hızlı tepki sağlar; uzlaştırma ise kaynak ve hedef arasında eksik kalan kayıtları aramak için ayrı bir güvence katmanıdır.

Kuyruk varsa veri kaybı imkânsız mı?

Hayır. Kalıcılık, erişim, yeniden deneme, saklama süresi ve izleme yanlış tasarlanabilir. Kabul testinde kuyruk çalışanını durdurup yeniden başlatın ve bekleyen işlerin davranışını doğrulayın.