Shopify Webhook Kurulumu ve Kullanımı Nasıl Yapılır?

Shopify Webhook Kurulumu Nedir? Shopify webhook kurulumu, mağazada belirli bir olay (yeni sipariş, stok değişimi, ürün güncellemesi) gerçekleştiğinde Shopify’ın bu bilgiyi otomatik olarak harici bir sunucuya HTTP POST isteğiyle iletmesini sağlayan yapılandırma sürecidir.

Shopify, webhook altyapısını hem Admin panelinden manuel tanımlama hem de Admin API üzerinden programatik oluşturma olarak iki yöntemle sunar (Shopify.dev, 2025). Panel üzerinden kurulum tek seferlik ve basit senaryolar için yeterliyken, API üzerinden kurulum bir uygulamanın kendi webhook’larını otomatik oluşturmasını gerektiren senaryolarda kullanılır.

Bu ayrım önemlidir çünkü yanlış yöntem seçimi, webhook’un mağaza sahibi Admin panelinde tema veya uygulama değişikliği yaptığında sessizce silinmesine yol açabilir. Bu rehber, hangi topic’in ne zaman kullanılacağını, HMAC doğrulamasının nasıl kurulacağını ve başarısız teslimatların nasıl yönetileceğini adım adım açıklar. Konuyla teknik olarak yakından ilişkili bir başka problem alanı Shopify API rate limit ve stok senkronizasyon hataları rehberinde ayrıca işlenir; çünkü yoğun webhook trafiği de rate limit sınırlarını zorlayabilir.

Shopify Webhook Nasıl Tanımlanır?

Webhook tanımlama, Shopify Admin panelinden “Notifications” ayarları üzerinden veya bir uygulamanın Admin API’si aracılığıyla webhookSubscriptionCreate mutasyonu çağrılarak yapılır. İki yöntem de aynı sonuca ulaşır: belirli bir topic için bir endpoint URL’i kaydedilir.

Admin panelinden webhook eklemek, kod yazmadan hızlı test yapmak isteyenler için uygundur ancak sınırlı topic listesi sunar. API üzerinden webhook oluşturma ise tüm topic listesine erişir ve bir uygulamanın kurulum sırasında kendi webhook’larını otomatik kaydetmesine imkan tanır bu, dağıtılan (public) app’lerin standart yöntemidir.

Quotable: Panel üzerinden eklenen bir webhook, mağaza sahibi tarafından fark edilmeden silinebilir; API üzerinden kurulan webhook ise uygulamanın kod tabanında tanımlı kaldığı için daha kalıcıdır.

Admin panelinden webhook eklemek için izlenecek adımlar şöyledir:

1. Shopify Admin → Settings → Notifications sayfasına gidin.
2. Sayfanın altındaki “Webhooks” bölümünde “Create webhook” seçeneğine tıklayın.
3. Tetiklenecek olayı (topic) açılır listeden seçin örneğin Order creation.
4. Format olarak JSON seçin (XML formatı yeni entegrasyonlarda önerilmez).
5. Webhook’un isteği göndereceği URL’i (endpoint) girin ve kaydedin.

API üzerinden kurulum ise GraphQL Admin API’de webhookSubscriptionCreate mutasyonuna topic, callback URL ve format parametreleri gönderilerek yapılır; bu yöntem Shopify özel API ve app entegrasyonu rehberinde anlatılan Admin API kimlik doğrulama yapısını kullanır.

Hangi Webhook Topic’leri En Sık Kullanılır?

En sık kullanılan webhook topic’leri sipariş, stok ve ürün yaşam döngüsündeki değişiklikleri kapsar; orders/create, orders/fulfilled, products/update ve inventory_levels/update bu listenin başında yer alır. Her topic, Shopify’ın belirlediği sabit bir veri şemasıyla (payload) gelir ve bu şema topic’e özgüdür.

orders/create topic’i, yeni bir sipariş oluştuğu anda tetiklenir ve ERP’ye sipariş aktarımı yapan entegrasyonların temelini oluşturur. orders/fulfilled ise sipariş kargoya verildiğinde tetiklenir; bu bildirim genelde müşteriye takip numarası e-postası gönderen sistemlerle entegre edilir. products/update bir ürünün fiyat, açıklama veya varyant bilgisi değiştiğinde çalışır ve pazaryeri senkronizasyonlarında kritik rol oynar.

İpucu: inventory_levels/update topic’i, stok her değiştiğinde tetiklenir ve yüksek hacimli mağazalarda saniyede birden fazla bildirim üretebilir. Bu topic’i dinleyen bir sistem, gelen veriyi kuyruğa (queue) alıp sırayla işlemeli; doğrudan işleme almak sunucuyu kilitleyebilir.

• orders/create yeni sipariş oluştuğunda ERP veya muhasebe sistemine aktarım için kullanılır.
• orders/fulfilled kargo bilgisi güncellendiğinde müşteri bildirimi tetiklemek için kullanılır.
• orders/cancelled iptal edilen siparişlerin stok iadesini otomatikleştirmek için kullanılır.
• products/update fiyat veya varyant değişikliğini pazaryerine yansıtmak için kullanılır.
• inventory_levels/update çoklu kanal stok senkronizasyonunun tetikleyicisidir.
• app/uninstalled uygulama kaldırıldığında ilgili müşteri verisinin silinmesini tetiklemek için kullanılır.

Shopify, GDPR ve veri gizliliği gerekliliklerine uyum için app/uninstalled, customers/data_request ve customers/redact gibi zorunlu uyumluluk (compliance) webhook’larının her genel uygulamada tanımlı olmasını şart koşar (Shopify.dev, 2025). Bu üç topic atlanırsa uygulama Shopify App Store onay sürecinden geçemez.

Webhook Güvenliği HMAC ile Nasıl Doğrulanır?

HMAC doğrulama, gelen webhook isteğinin gerçekten Shopify’dan geldiğini ve yolda değiştirilmediğini kanıtlayan kriptografik imza kontrolüdür. Her webhook isteği, X-Shopify-Hmac-SHA256 header’ında bu imzayı taşır ve alıcı sunucu bu imzayı kendi hesapladığı değerle karşılaştırarak doğrular.

Doğrulama işlemi, mağazanın webhook paylaşılan sırrı (shared secret) ile istek gövdesinin (body) SHA-256 algoritmasıyla şifrelenmesi ve sonucun Base64 formatına çevrilmesiyle yapılır. Sunucu tarafında hesaplanan bu değer, header’daki değerle birebir eşleşmiyorsa istek reddedilmelidir.

Quotable: HMAC imzası eşleşmeyen bir webhook isteği asla işlenmemeli; bu kontrolün atlanması, sahte isteklerle stok veya sipariş verisinin manipüle edilmesine kapı açar.

Uzak Durulması Gereken Risk: HMAC doğrulamasını atlayıp sadece URL’in gizli tutulmasına güvenmek yeterli bir güvenlik önlemi değildir. Endpoint URL’i loglardan, tarayıcı geçmişinden veya ağ trafiğinden sızabilir; imza kontrolü olmadan bu sızıntı doğrudan sahte veri girişine dönüşür.

HMAC doğrulamasının pratikte doğru kurulup kurulmadığını test etmenin en güvenilir yolu, Shopify Admin panelindeki webhook günlüğünden gerçek bir test isteği göndermek ve sunucu loglarında imza karşılaştırmasının başarılı döndüğünü doğrulamaktır. Bu test, canlıya geçmeden önce mutlaka yapılmalıdır.

Webhook Teslimatı Başarısız Olursa Ne Olur?

Shopify, bir webhook isteği hedef sunucudan başarılı yanıt (2xx durum kodu) alamazsa isteği otomatik olarak yeniden dener; yeniden deneme aralıkları giderek uzayan bir zamanlama (exponential backoff) izler ve toplam deneme süresi 48 saate kadar uzayabilir (Shopify.dev, 2025). Bu süre boyunca sunucu ayakta gelirse, gecikmiş bildirim gecikmeyle de olsa teslim edilir.

48 saatlik pencere içinde sunucu hâlâ yanıt vermiyorsa Shopify webhook’u kalıcı olarak başarısız sayar ve o olaya ait bildirim bir daha gönderilmez. Bu durum, uzun süreli bir sunucu kesintisinde geriye dönük veri kaybına yol açabilir bu yüzden webhook’a bağımlı sistemlerde periyodik bir “uzlaştırma” (reconciliation) sorgusu yedek mekanizma olarak kurulmalıdır.

Kritik Not: Webhook tek başına güvenilir bir veri kaynağı değildir; sadece hızlı bildirim sağlar. Kritik veriler için günde bir kez Admin API üzerinden tam senkronizasyon kontrolü yapılması, kaçırılan webhook’ların telafi edilmesini sağlar.

Bu davranış, sunucu tarafının webhook isteğini aldığı anda hemen 200 yanıtı dönüp asıl işlemi arka planda (kuyruk üzerinden) yapması gerektiğini gösterir. İşlem tamamlanana kadar yanıtı geciktiren sunucular, Shopify’ın zaman aşımı sınırına takılıp gereksiz yeniden denemelere neden olur.

Webhook Kurulumunda En Sık Yapılan Hatalar Nelerdir?

En sık yapılan hata, endpoint URL’inin HTTPS olmamasıdır; Shopify, 2022’den itibaren yalnızca HTTPS protokolü ile çalışan webhook endpoint’lerini kabul eder (Shopify.dev, 2025). HTTP üzerinden tanımlanmaya çalışılan bir webhook, kurulum aşamasında reddedilir.

İkinci yaygın hata, sunucunun webhook isteğini işlerken uzun süren bir işlem (örneğin senkron bir üçüncü parti API çağrısı) yapıp yanıtı geciktirmesidir. Shopify’ın zaman aşımı süresi kısadır; bu süre aşıldığında istek başarısız sayılır ve gereksiz retry döngüsü başlar.

Peki bu hata pratikte nasıl fark edilir? Mağaza sahibi genelde stok verisinin “bazen” güncel olmadığını fark eder, ama sorunun kaynağının yavaş yanıt veren webhook endpoint’i olduğunu anlamak için sunucu loglarına bakmak gerekir.

Üçüncü hata, aynı topic için birden fazla webhook’un yanlışlıkla tanımlanmasıdır bu durum aynı olayın birden fazla kez işlenmesine (duplicate processing) yol açar ve örneğin bir siparişin ERP’ye iki kez aktarılmasına neden olabilir. Webhook işleyicisinin, gelen her isteğin benzersiz X-Shopify-Webhook-Id header’ını kontrol ederek daha önce işlenmiş isteği tekrar işlememesi gerekir.

Webhook Payload Yapısı Nasıl Okunur?

Her webhook isteği, JSON formatında bir gövde (payload) taşır ve bu gövdenin alan yapısı seçilen topic’e göre sabittir; orders/create topic’i sipariş numarası, satır kalemleri ve müşteri bilgisini içerirken inventory_levels/update yalnızca envanter kimliği ve yeni stok miktarını taşır. Payload’un tam şemasını bilmeden bir işleyici yazmak, eksik veya yanlış alan okumaya yol açar.

Shopify her webhook isteğine standart header’lar ekler: X-Shopify-Topic hangi olayın tetiklendiğini, X-Shopify-Shop-Domain hangi mağazadan geldiğini, X-Shopify-Webhook-Id ise isteğin benzersiz kimliğini taşır. Bu üç header, tek bir endpoint’in birden fazla mağazadan veya birden fazla topic’ten gelen isteği doğru şekilde ayırt etmesini sağlar.

Quotable: X-Shopify-Shop-Domain header’ı olmadan çoklu mağaza destekleyen bir uygulama, gelen webhook’un hangi mağazaya ait olduğunu ayırt edemez.

Bir örnek üzerinden gitmek gerekirse, orders/create payload’ı içinde line_items dizisi sipariş edilen her ürünü ayrı bir nesne olarak listeler; bu dizinin her elemanında variant_id, quantity ve price alanları bulunur. ERP’ye sipariş aktaran bir entegrasyon, bu diziyi döngüyle işleyerek her satırı ayrı bir fatura kalemine dönüştürür.

Webhook Testi İçin Hangi Araçlar Kullanılır?

Yerel geliştirme ortamında webhook testi yapmak için genelde bir tünelleme (tunneling) aracı kullanılır; bu araçlar geliştiricinin bilgisayarındaki yerel sunucuyu geçici bir genel (public) URL üzerinden erişilebilir hale getirir. Shopify CLI, bu tünelleme işlemini kendi içine gömülü olarak sunar ve shopify app dev komutu çalıştırıldığında otomatik bir test URL’i üretir.

Shopify CLI olmadan geliştirme yapan ekipler, ngrok veya benzeri bir tünelleme aracını yerel sunucuya bağlayıp bu geçici URL’i webhook endpoint’i olarak tanımlayabilir. Bu yöntem, canlı sunucuya her küçük değişiklikte kod yüklemeden (deploy) hızlı test döngüsü kurar.

İpucu: Shopify CLI ile geliştirilen uygulamalarda webhook abonelikleri shopify.app.toml dosyasında tanımlanır ve shopify app deploy komutu çalıştırıldığında otomatik olarak Shopify’a kaydedilir; bu, panelden manuel webhook eklemeyle karşılaştırıldığında sürüm kontrolü (version control) avantajı sağlar.

Test sürecinde webhook isteğinin gerçekten doğru şemada geldiğini doğrulamanın en pratik yolu, Shopify Admin panelindeki “Notifications” sayfasından bir test isteği tetiklemek ve sunucu loglarında gelen payload’ı incelemektir. Bu adım, canlı bir sipariş oluşturmadan webhook akışının uçtan uca çalıştığını kanıtlar.

1. Shopify CLI ile yerel geliştirme sunucusunu başlatın ve otomatik tünel URL’ini not edin.
2. Webhook aboneliğini shopify.app.toml dosyasında ilgili topic için tanımlayın.
3. Admin panelinden veya gerçek bir test siparişiyle olayı tetikleyin.
4. Sunucu loglarında payload’ın ve HMAC imzasının doğru geldiğini kontrol edin.
5. Test başarılıysa, üretim ortamına geçmeden önce canlı bir HTTPS endpoint’e webhook aboneliğini güncelleyin.

Tek Endpoint Üzerinden Birden Fazla Webhook Nasıl Yönetilir?

Bir entegrasyon birden fazla topic dinliyorsa, her topic için ayrı bir endpoint URL’i açmak yerine tek bir endpoint üzerinden gelen X-Shopify-Topic header’ına göre dallanma (routing) yapmak bakımı büyük ölçüde basitleştirir. Tek endpoint yaklaşımı, HMAC doğrulama kodunun tek bir yerde tutulmasını ve yeni bir topic eklendiğinde sadece routing mantığına bir satır eklenmesini sağlar.

Bu mimaride tipik akış şöyle işler: istek geldiğinde önce HMAC imzası doğrulanır, ardından X-Shopify-Topic header’ı okunarak isteğin hangi işleyici fonksiyona yönlendirileceğine karar verilir, son olarak işlenen veri bir kuyruğa (queue) yazılarak asıl iş mantığı arka planda çalıştırılır. Bu üç adımın sırası değiştirilmemeli doğrulama her zaman ilk adım olmalıdır.

Kritik Not: HMAC doğrulamasını routing’den sonra yapmak, sahte bir isteğin işleyici fonksiyona kadar ulaşmasına izin verir. Doğrulama her zaman payload işlenmeden önce, ilk satırda yapılmalıdır.

Çoklu mağaza destekleyen bir uygulamada bu mimari bir adım daha genişler: X-Shopify-Shop-Domain header’ı üzerinden hangi mağazanın webhook gönderdiği tespit edilir ve her mağazanın kendi API kimlik bilgileri (credentials) ile eşleştirilir. Bu eşleştirme yapılmazsa, bir mağazanın verisi yanlışlıkla başka bir mağazanın kaydına yazılabilir çoklu kiracılı (multi-tenant) uygulamalarda en kritik hata kaynaklarından biri budur.

Bu mimari tercih, özellikle 5’ten fazla topic dinleyen orta ve büyük ölçekli entegrasyonlarda zaman kazandırır; az sayıda topic dinleyen basit projelerde ayrı endpoint yaklaşımı da yeterli kalabilir.

Sık Sorulan Sorular

Shopify webhook kurulumu için kod yazmak zorunlu mu? Admin panelinden basit bir webhook eklemek kod gerektirmez, ancak gelen isteği alıp işleyecek bir sunucu (endpoint) mutlaka bir yazılımla çalışmalıdır. Sunucu tarafı olmadan webhook’un bildirimi bir yere ulaşmaz.

Webhook ile Shopify Flow arasındaki fark nedir? Webhook, harici bir sunucuya veri gönderirken Shopify Flow, Shopify ekosistemi içinde kod yazmadan otomasyon kurar. Harici bir ERP veya özel sisteme veri aktarımı gerekiyorsa webhook, Shopify içi basit kurallar için Flow tercih edilir.

Bir webhook kaç kez yeniden denenir? Shopify başarısız bir webhook’u üstel geri çekilme (exponential backoff) mantığıyla toplam 48 saat boyunca yeniden dener. Bu sürenin sonunda hâlâ başarısız olan istek kalıcı olarak silinir.

Webhook verisi kaybolursa nasıl telafi edilir? Kritik veri akışlarında günlük bir Admin API senkronizasyon kontrolü yedek mekanizma olarak kurulmalıdır. Bu kontrol, kaçırılan webhook bildirimlerini tespit edip eksik veriyi tamamlar.

HMAC doğrulaması olmadan webhook güvenli midir? Hayır, HMAC doğrulaması olmadan endpoint URL’i bilen herkes sahte veri gönderebilir. Her webhook işleyicisinde imza kontrolü zorunlu tutulmalıdır.

Shopify webhook kurulumu ile API rate limit arasında bir ilişki var mı? Evet, webhook’un kendisi rate limit’e sayılmaz ama webhook geldiğinde tetiklenen API çağrıları (örneğin sipariş detayını çekmek) rate limit’i tüketir. Yoğun webhook trafiğinde bu çağrıların nasıl yönetileceği Shopify API rate limit ve stok senkronizasyon hataları rehberinde ele alınır.

Webhook endpoint’i geçici olarak kapalıysa veri kaybolur mu? Hayır, Shopify 48 saat boyunca artan aralıklarla yeniden deneme yapar; endpoint bu süre içinde tekrar erişilebilir hale gelirse bildirim gecikmeli de olsa ulaşır. 48 saati aşan kesintilerde ise bildirim kalıcı olarak kaybolur ve günlük uzlaştırma sorgusuyla telafi edilmelidir.

Bir mağaza teması değiştirildiğinde webhook’lar silinir mi? Hayır, tema değişikliği webhook aboneliklerini etkilemez; webhook’lar tema katmanından bağımsız olarak uygulama veya Admin panel seviyesinde tanımlıdır. Ancak bir uygulama tamamen kaldırılırsa o uygulamaya ait tüm webhook abonelikleri otomatik olarak silinir.

Webhook ile REST API polling’i birlikte kullanmak gerekir mi? Çoğu senaryoda hayır, webhook tek başına yeterlidir. Ancak kritik veri akışlarında (örneğin muhasebe senkronizasyonu) günlük bir doğrulama sorgusu, kaçırılan webhook bildirimlerini yakalamak için tamamlayıcı bir güvenlik katmanı olarak önerilir.

Bir mağazada aynı topic için kaç webhook tanımlanabilir? Shopify, aynı topic için birden fazla endpoint’e webhook gönderilmesine teknik olarak izin verir, ancak bu genelde önerilmez çünkü aynı olayın birden fazla sistemde tekrar işlenmesine yol açabilir. Tek bir merkezi endpoint üzerinden routing yapmak, bu tekrarı önleyen daha sağlam bir yaklaşımdır.

Sonraki Adım

Webhook kurulumu tamamlandıktan sonra, yüksek hacimli mağazalarda webhook’ların tetiklediği API çağrılarının rate limit sınırına takılıp takılmadığı izlenmelidir. Bu konudaki leaky bucket ve cost-based limit mekanizmaları Shopify API rate limit ve stok senkronizasyon hataları rehberinde derinlemesine anlatılır. Webhook’un genel API mimarisindeki yeri hakkında daha geniş bir bakış için Shopify özel API ve app entegrasyonu rehberine bakılabilir.