Webhooks

BYNovax'taki commerce değişikliklerini entegratör sistemine otomatik iletir.

Endpointler

GET/webhooksEndpointleri listele

POST/webhooksWebhook endpoint oluştur

DELETE/webhooks/{webhook}Webhook sil

Event	Ne zaman gelir?
product.created	Ürün oluşturulduğunda
product.updated	Ürün güncellendiğinde
inventory.updated	Stok değiştiğinde
pricing.updated	Fiyat değiştiğinde
order.created	Yeni satış oluştuğunda
order.updated	Sipariş durumu değiştiğinde
order.shipped	Sipariş kargoya verildiğinde

Webhook ne işe yarar?

Webhook, BYNovax tarafında önemli bir olay gerçekleştiğinde sisteminizin sürekli polling yapmasını beklemeden sizin HTTP endpointinize event gönderilmesini sağlar.

Örneğin yeni sipariş geldiğinde veya stok/fiyat değiştiğinde dış sisteminiz olaydan haberdar olabilir.

Gerekli scope'lar

İşlem	Scope
GET /webhooks	webhooks:read
POST /webhooks	webhooks:write
DELETE /webhooks/{webhook}	webhooks:write

Desteklenen canonical eventler

Event	Anlamı
product.created	Ürün oluşturuldu
product.updated	Ürün güncellendi
inventory.updated	Stok değişti
pricing.updated	Fiyat değişti
order.created	Sipariş oluşturuldu
order.updated	Sipariş güncellendi
order.shipped	Sipariş kargolandı

Webhook oluşturma

POST /webhooks çağrısında url ve events gönderilir. URL public olarak erişilebilir olmalı ve backend URL/DNS güvenlik kontrollerinden geçmelidir.

events array'i 1 ile 20 arasında benzersiz canonical event değeri içermelidir.

Signing secret

Webhook oluşturulduğunda response içerisinde signing_secret döner. Bu secret yalnızca oluşturma sırasında gösterilir; daha sonra aynı plaintext secret tekrar alınamaz.

Secret değerini güvenli secret storage içerisinde saklayın ve webhook doğrulama işlemlerinizde kullanın.

POST /webhooks başarılı olduğunda HTTP 201 Created döner.

Webhook kayıt alanları

Alan	Açıklama
id / uid	Webhook kimliği
url	Eventlerin gönderileceği adres
events	Abone olunan canonical eventler
active	Webhook aktiflik durumu
last_success_at	Son başarılı delivery zamanı
last_failure_at	Son başarısız delivery zamanı
consecutive_failures	Ardışık başarısızlık sayısı
disabled_at	Varsa devre dışı bırakılma zamanı

Receiver nasıl tasarlanmalı?

Endpoint hızlı şekilde 2xx response döndürmeli.
Ağır işi request thread içerisinde yapmak yerine queue'ya aktarın.
Aynı event birden fazla kez gelebileceği için duplicate-safe işleyin.
Event processing işlemini idempotent tasarlayın.
Webhook secret değerini loglamayın.

Retry ve duplicate davranışı

Network problemi veya alıcı endpoint hatası nedeniyle aynı webhook tekrar gönderilebilir. Bu nedenle 'aynı event yalnız bir kez gelir' varsayımı yapmayın.

Event kimliği veya business resource kimliği üzerinden duplicate koruması uygulayın.

Webhook kapatma

DELETE /webhooks/{webhook} kayıt üzerinde soft disable davranışı uygular. Response webhook active=false olarak dönebilir.

Aynı disable işleminin tekrar edilmesi güvenli/idempotent olacak şekilde ele alınmalıdır.

Örnek gerçek entegrasyon

BYNovax → order.created webhook
        ↓
Sizin /webhooks/bynovax endpointiniz
        ↓
Request doğrulanır
        ↓
Event queue'ya yazılır
        ↓
HTTP 200 hızlıca döner
        ↓
Worker GET /orders/{order} ile güncel siparişi alır
        ↓
ERP siparişi idempotent şekilde oluşturur

Çalıştığını nasıl doğrularım?

Webhook create response HTTP 201.
signing_secret güvenli şekilde kaydedildi.
Receiver public HTTPS endpoint olarak erişilebilir.
Receiver duplicate eventleri tolere ediyor.
Başarısız delivery'ler gözlemleniyor.
Webhook listesinde last_success_at güncelleniyor.

Webhook production consumer contractı

Kural	Uygulama
Acknowledgement	Event güvenli şekilde kabul edildikten sonra hızlı 2xx dönün
Idempotency	Aynı event tekrar gelebilir; duplicate-safe consumer kullanın
Queue	Uzun işleri HTTP request thread dışında yürütün
Secret	signing_secret yalnız create response sırasında gösterilir; loglamayın
Reconciliation	Gerektiğinde event resource ID ile API'den güncel state okuyun
Monitoring	last_success_at, last_failure_at ve consecutive_failures alanlarını izleyin

Webhook + polling reconciliation

Webhook event geldi
        ↓
Event duplicate kontrolü
        ↓
Queue'ya yaz
        ↓
İlgili GET endpointinden authoritative state oku
        ↓
ERP state idempotent güncelle
        ↓
Periyodik polling ile reconciliation yap

Event tüketim önerisi

order.created ve order.updated eventlerinde GET /orders/{order} ile authoritative sipariş state okunabilir.
order.shipped eventinde shipment state ayrıca okunabilir.
product.created ve product.updated eventlerinde product API güncel state için kullanılabilir.
inventory.updated ve pricing.updated eventlerinde event sinyalini ilgili authority API ile reconcile edin.
Webhook delivery'yi tek ve kesin state snapshotı olarak değil, değişiklik sinyali olarak değerlendirmek daha dayanıklı entegrasyon sağlar.

Webhook consumer kuralları

HTTP 2xx ile hızlı acknowledgement dönün.
Event ID'yi kendi sisteminizde dedupe edin.
İşlem uzun sürecekse kendi queue sisteminize alın.
Retry halinde aynı commerce event tekrar gelebilir; consumer idempotent olmalıdır.