Webhook Modeli V1

Webhook olay zarfı, desteklenen olay türleri ve imza doğrulaması.

Olay Modeli

İmzalı webhook bildirimi

Bulbulustur webhook aboneliğine bir HTTP POST isteği gönderir. İleti JSON gövdesiyle gelir; istemci Bulbulustur'a olay göndermez.

{
  "id": "delivery-guid",
  "type": "order.created",
  "storeId": 123,
  "createdAt": "2026-10-30T09:00:00Z",
  "data": { }
}

Olay türleri: order.created, order.updated, return.created, return.updated. Abonelik oluştururken * tüm olay türlerini seçer.

data alanının içeriği olay üreticisine bağlıdır; tüm olaylar için tek ve sabit bir sipariş/iadeye özgü DTO varsaymayın.

Desteklenen türlerin bulunması olayların otomatik yayımlandığı anlamına gelmez. Canlı üretim olayları için ilgili sipariş/iade iş akışından yayın entegrasyonunun ayrıca etkin olması gerekir.

İmza ve Teslimat

HMAC-SHA256 doğrulama

Gelen istek başlıkları: X-Bulbulustur-Event, X-Bulbulustur-Delivery ve X-Bulbulustur-Signature.

İmza başlığı biçimi: t=unix_timestamp,v1=hex_hmac. İmza, abonelik oluşturma yanıtında yalnızca bir kez verilen signingSecret ile HMAC-SHA256(secret, UTF8(timestamp + "." + rawBody)) üzerinden hesaplanır.

Gövdeyi yeniden JSON'a çevirmeden önce ham gövde baytları üzerinden imzayı kontrol edin. Zaman damgası için kısa bir tolerans penceresi ve teslimat kimliği üzerinden idempotency kullanın; sabit süreli imza karşılaştırması yapın.

Başarısız teslimatta toplam üç deneme yapılır. Art arda 10 başarısız teslimattan sonra abonelik pasifleşir. Yanıtın 2xx olması başarılı teslimat sayılır.