​
Webhooks ve Storefront Scripts

Hemen Storefront olaylarına abone olma ve yönetme. Hemen Builders webhook ve storefront script katmanı, app’lerin mağaza olaylarına güvenli şekilde tepki vermesini ve storefront’a kontrollü JavaScript eklemesini sağlar. Webhooklar sunucu tarafı entegrasyonlar için, Storefront Event Bus ise tarayıcıdaki commerce olaylarını yakalamak için kullanılır.
Bu mekanizmayı kullanmak için iki ana yol bulunur:
  • Webhook endpoint’i: order.created veya product.updated gibi backend olaylarını imzalı HTTP payload olarak alırsınız.
  • Storefront script: PAGE_VIEW, PRODUCT_VIEW, ADD_TO_CART gibi browser eventlerini izinli script içinde dinlersiniz.

​
Webhook eventleri

Başlangıç event örnekleri: 
order.created
order.paid
order.cancelled
product.updated
stock.changed
Webhook endpointleri tenant admin panelinden veya API üzerinden app bazlı yönetilir.

​
İmza başlıkları

Yeni standart: 
HM-Event-Id
HM-Event-Type
HM-Tenant-Id
HM-Timestamp
HM-Signature
Webhook receiver, HM-Timestamp ve body payload üzerinden HMAC SHA256 imzasını doğrulamalıdır. Aynı HM-Event-Id birden fazla gelirse idempotent işlenmelidir.

​
Webhook oluşturma

curl -X POST "https://dev.hemenmagaza.com/api/builders/v1/webhooks" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{
    "url": "https://example.com/hemen/webhooks",
    "events": ["order.created", "product.updated"]
  }'

​
Storefront script registry

Script create endpoint: 
POST /api/builders/v1/storefront-scripts
Storefront script list endpoint: 
GET /api/storefront/{storefront}/builders/scripts
Örnek script kaydı: 
{
  "storefront_id": "main",
  "name": "Analytics Pixel",
  "script_url": "https://cdn.example.com/pixel.js",
  "placement": "body_end",
  "priority": 50,
  "consent_required": true,
  "allowed_events": ["PAGE_VIEW", "PRODUCT_VIEW", "COMPLETE_CHECKOUT"],
  "status": "active"
}

​
Event Bus standardı

Storefront runtime şu eventleri yayınlar: 
PAGE_VIEW
PRODUCT_VIEW
ADD_TO_CART
REMOVE_FROM_CART
VIEW_CART
BEGIN_CHECKOUT
COMPLETE_CHECKOUT
CUSTOMER_LOGIN
CUSTOMER_REGISTER
Örnek dinleyici: 
window.HemenStorefrontEvents?.on('ADD_TO_CART', (event) => {
  console.log(event.name, event.payload);
});
consent_required = true olan scriptler kullanıcı izni alınmadan yüklenmez. Inline script varsayılan kapalıdır. Script listesi tenant ve storefront bazlı cache key ile tutulur.

​
Tenant izolasyonu

Script listesi şu anahtarla ayrılır: 
tenant_id + storefront_id
Bir tenant’ın script’i başka tenant storefront’unda listelenemez, yüklenemez veya event alamaz.