xShopum • Webhook Entegrasyon Rehberi

Webhook (PUSH) ile Stok & Fiyat Güncellemeleri

Bu rehber; xShopum üzerinde gerçekleşen stok ve fiyat değişikliklerini kendi sisteminize
gerçek zamanlı olarak almanız için hazırlanmıştır.
Webhook modeli “siz çekin” değil; biz size gönderelim (push) mantığıyla çalışır.

✅ HMAC imzalı güvenli gönderim
✅ Collector ile tek event
✅ Anında flush (cron beklemez)
✅ Başarısızsa retry kuyruğu

Bu rehber kimler için?
Bu doküman; kendi altyapısını geliştiren veya sisteme özel entegrasyon yazan yazılımcılar, ajanslar ve entegrasyon firmaları için hazırlanmıştır.Önemli not: Webhook, toplu veri çekme (ürünleri komple import etme) sistemi değildir. Toplu veri senaryoları için XML/Feed kullanılır; webhook ise yalnızca değişiklik bildirimi gönderir.
Bu sayfada ne var?
1) Mantık & kapsam • 2) Güvenlik (HMAC) • 3) Event tipi & alanlar • 4) Header’lar • 5) Örnek JSON • 6) İmza doğrulama • 7) Idempotency/tekrarlar • 8) Retry mantığı • 9) Ürün eşlemesi • 10) Test & debug • 11) Sık yapılan hatalar

1) Webhook Mantığı: XML’den Farkı

XML entegrasyonu “siz belli aralıklarla çekersiniz” (poll) yaklaşımıdır.
Webhook ise “biz değişiklik oldukça size göndeririz” (push) yaklaşımıdır.

Webhook ne zaman ideal?
  • Stok/fiyat değişikliklerini anlık almak istiyorsanız
  • Gün içinde “kaçırma” olmadan otomatik güncelleme istiyorsanız
  • Entegrasyonunuzda “event bazlı” iş akışı varsa
Pratik öneri
Webhook’u “anlık değişiklik” için kullanın. Sisteminizde güvenlik için ayrıca
periyodik (ör. gecelik) XML doğrulaması yapmak isteğe bağlı iyi bir pratiktir.

2) Kapsam: Hangi Değişiklikler Bildirilir?

Bu webhook sistemi, ürün üzerinde gerçekleşen stok ve fiyat değişikliklerini event bazlı olarak bildirir. Webhook bir “veri çekme” (import) mekanizması değil, yalnızca değişiklik bildirimi sağlar.

Aynı “kaydet” işlemi sırasında birden fazla değişiklik oluşsa bile, collector mekanizması sayesinde tüm değişiklikler tek bir webhook event’i olarak gönderilir.

Bildirilen değişiklik türleri (örnek):
• inventory — Satılabilir stok miktarı ve stok durumu
• pricing — Liste / satış fiyatı
• dealer_pricing — Bayi / toptan fiyatlar
• status — Ürün satış durumu (instock / outofstock vb.)
Collector TTL:
Aynı kayıt sırasında peş peşe oluşan değişiklikler 6 saniyelik bir zaman penceresinde toplanır ve tek event olarak iletilir.

3) Güvenlik: HMAC Signature (Zorunlu)

Webhook isteği, bayi panelinde görünen Webhook Secret ile imzalanır. Alıcı sistem, gelen isteğin gerçekten xShopum’dan geldiğini anlamak için X-XSU-Signature doğrulaması yapmalıdır.

İmza yöntemi:
Body JSON’u alınır → HMAC-SHA256 hesaplanır → sonuç base64 ile encode edilip header’a yazılır.
Güvenlik notu: Secret’ı kod içine gömmeyin. Environment variable / config olarak saklayın. SSL (HTTPS) olmadan webhook kullanmamanız önerilir.

4) Gönderim Formatı: Header’lar

Webhook çağrısı HTTP POST olarak gelir ve aşağıdaki header’ları içerir:

Header Açıklama Not
Content-Type JSON içerik application/json; charset=utf-8
X-XSU-Event-Id Event benzersiz kimliği Idempotency için kullanın
X-XSU-Event-Type Event tipi product.stock_price.changed
X-XSU-Occurred-At Event oluşma zamanı (UTC) ISO8601
X-XSU-Signature HMAC imza (base64) Zorunlu doğrula
X-XSU-Subscriber-Id Abone kimliği Örn: dealer_123 veya admin_1
Alıcı sistem ne dönmeli? Başarılı kabul için 2xx cevap dönmeniz yeterlidir. 4xx/5xx durumlarında sistem retry kuyruğuna alır.

5) Örnek Event JSON (Schema v1.0)

Gönderilen body JSON’u aşağıdaki şemayı takip eder. Önemli alanlar: event_id, event_type, payload.sku. change.fields alanı, bu event’te hangi “alan gruplarının” değiştiğini gösterir.

{
  "schema_version": "1.0",
  "event_id": "xsu_9f1c1d3a0b0e2d9c1a7b0c33",
  "event_type": "product.stock_price.changed",
  "occurred_at": "2026-02-09T12:34:56Z",
  "source": { "platform": "xShopum", "channel": "woocommerce" },
  "change": {
    "reason": "product_save",
    "fields": ["inventory", "pricing", "dealer_pricing"]
  },
  "payload": {
    "product_id": 1615,
    "parent_id": null,
    "type": "simple",
    "sku": "XSU-XSU-K1012",
    "name": "14 cm Vantuzlu Jel Anal Plug",
    "permalink": "https://.../urun/...",
    "pricing": { "currency": "TRY", "regular": 399.90, "sale": 305.00, "active": 305.00 },
    "inventory": { "manage_stock": true, "quantity": 247, "status": "instock" },
    "dealer_pricing": {
      "wholesale_usd_vat": "12.50",
      "wholesale_tl_ex_tax": "300.00",
      "wholesale_tl_inc_tax": "360.00"
    },
    "updated_at": "2026-02-09T12:33:10Z",
    "attributes": null
  }
}
change.fields örnekleri:
inventory (stok), pricing (fiyat), dealer_pricing (bayi fiyatları), status (instock/outofstock vb.)
change.reason örnekleri:
product_save, stock_set, price_set, status_set, manual_test

6) İmza Doğrulama (Zorunlu)

Doğrulama adımları:
(1) raw body’yi alın,
(2) secret ile HMAC-SHA256 hesaplayın,
(3) base64’e çevirin,
(4) header’daki X-XSU-Signature ile karşılaştırın.

Pseudocode
expected = base64(hmac_sha256(secret, raw_body))
if expected != header_signature → reject
Önemli
Body üzerinde boşluk/format değişikliği yaparsanız imza tutmaz.
İmzayı doğrularken raw body kullanın.

7) Idempotency: Aynı Event 2 Kez Gelebilir

Network hataları / timeout / retry nedeniyle aynı event tekrar gönderilebilir. Bu yüzden alıcı sistem X-XSU-Event-Id (veya body içindeki event_id) üzerinden “bu event’i daha önce işledim mi?” kontrolü yapmalıdır.

Önerilen pratik: Son 7–30 günün event_id kayıtlarını saklayın. Aynısı gelirse 200 OK dönüp yeniden işlemeyin.

8) Retry Mekanizması (Max 6 Deneme)

Webhook gönderimi başarısız olursa (2xx dışında cevap / bağlantı hatası), sistem otomatik olarak retry kuyruğuna ekler. Maksimum 6 deneme yapılır.

Attempt Gecikme Not
1 5 dk İlk hata sonrası
2 10 dk —
3 20 dk —
4 40 dk —
5 80 dk —
6 160 dk Max deneme
Timeout: Webhook çağrısı için timeout 12 saniyedir. Alıcı sistem mümkünse hızlı 2xx dönüp işi arka planda (queue) işlemelidir.

9) Entegrasyon Notları (Ürün Eşlemesi)

Webhook payload’ı içinde yer alan sku, xShopum tarafındaki ürünün benzersiz referans anahtarıdır.

Alıcı sistem;

  • xShopum SKU’sunu kendi sistemindeki bir ürünle eşleyebilir,
  • Kendi SKU yapısını koruyabilir,
  • Gerekirse xShopum SKU’sunu external_id / supplier_sku gibi bir alanda saklayabilir.
Öneri: Eşleme işlemi, alıcı sistemin kendi mimarisine göre tekil (unique) olacak şekilde tasarlanmalıdır.

10) Test Gönderimi & Debug

Bayi panelinde “Test Gönder” butonu ile sisteminize örnek webhook gönderilebilir. Başarılı cevap döndürürseniz ekranda HTTP kodu ve Event ID görünür.

Test sırasında önerilen kontrol listesi:
1) Endpoint HTTPS mi? • 2) 2xx dönüyor mu? • 3) Signature doğrulaması yapılıyor mu? • 4) Event ID loglanıyor mu? • 5) Body raw halde saklanabiliyor mu?
İpucu: İlk kurulumda alıcı sistem “ok” gibi kısa bir response dönebilir. Önemli olan 2xx dönmeniz ve signature doğrulamasını doğru yapmanızdır.

Son kontrol: En çok yapılan 9 hata
1) Signature doğrulamamak • 2) Body’yi parse edip “yeniden stringify” ederek imzayı bozmaya çalışmak • 3) 2xx dönmemek • 4) Endpoint içinde uzun işlem yapıp timeout’a düşmek • 5) Event ID ile idempotency yapmamak • 6) SSL/HTTPS kullanmamak • 7) Secret’ı repo içine koymak • 8) IP/Firewall yüzünden webhook’u engellemek • 9) Log tutmamak

Devam / Yardım

Bu sayfa, webhook push mantığını ve güvenlik doğrulamasını anlatır. Toplu ürün çekme / import senaryoları için XML entegrasyon rehberini kullanabilirsiniz.