Webhook Bildirimleri
Sürekli sorgulama (polling) yapmak yerine sipariş, ürün ve stok olaylarını Armonika'dan kendi HTTPS sunucunuza imzalı POST bildirimleri olarak anlık alın.
Desteklenen Olay Türleri & Yeniden Deneme Politikası
Armonika sunucunuza JSON gövdeli bir POST isteği gönderir ve 5 saniye içinde 2xx (200–299) HTTP yanıtı bekler. Zaman aşımı veya 5xx hatası alınırsa teslimat üstel geri çekilmeyle (1 dk, 5 dk, 30 dk, 2 saat, 6 saat) en fazla 5 kez yeniden denenir.
| Olay Kodu (event) | Tetiklenme Koşulu |
|---|---|
| order.created | Herhangi bir bağlı satış kanalından yeni bir sipariş düştüğünde tetiklenir. |
| order.status_updated | Siparişin durumu (hazırlanıyor, kargoda, teslim edildi, iade) değiştiğinde tetiklenir. |
| order.cancelled | Sipariş müşteri veya pazaryeri tarafından iptal edildiğinde tetiklenir. |
| product.updated | Ürün veya varyant bilgileri (başlık, barkod, fiyat) değiştiğinde tetiklenir. |
| inventory.updated | Bir varyantın kullanılabilir stok miktarı değiştiğinde tetiklenir. |
| discrepancy.detected | Ana stok/fiyat kaynağı ile pazaryeri ilanı arasında fark oluştuğunda tetiklenir. |
X-Armonika-Signature (HMAC-SHA256) Doğrulaması
Gelen isteğin gerçekten Armonika'dan geldiğini ve yolda değiştirilmediğini doğrulamak için mağazanızın Secret Key (arm_sec_...) değeriyle X-Armonika-Signature başlığını mutlaka kontrol edin:
- 1. İmzalanan Metni Oluşturun:
X-Armonika-Timestampbaşlığı ile ayrıştırılmamış ham istek gövdesini (rawBody) nokta (.) ile birleştirin:${timestamp}.${rawBody}. - 2. HMAC-SHA256 Hesaplayın: Mağaza
Secret Keydeğerinizle hex özetini üretin vesha256=<hex>biçiminde sabit süreli (timingSafeEqual) karşılaştırın.
/v1/webhooksKayıtlı Webhook Uçlarını Listele
Mağaza için kendi sunucunuza tanımladığınız tüm giden (outbound) webhook aboneliklerini, dinlenen olay türlerini ve teslimat sağlık durumunu döndürür.
/v1/webhooks/v1/webhooksYeni Webhook Aboneliği Oluştur
HTTPS sunucu adresinizi seçilen Armonika olaylarına abone yapar. Teslimatlar mağazanızın Secret Key değeriyle HMAC-SHA256 olarak imzalanır ve X-Armonika-Signature başlığında gönderilir.
İstek Parametreleri
| Alan | Konum | Tip | Zorunluluk | Açıklama |
|---|---|---|---|---|
| url | Body (JSON) | string (https url) | Zorunlu | Bildirimlerin POST edileceği genel erişime açık HTTPS uç nokta adresi. |
| events | Body (JSON) | string[] | Zorunlu | Abone olunacak olaylar: order.created, order.status_updated, order.cancelled, product.updated, inventory.updated, discrepancy.detected. |
| description | Body (JSON) | string | Opsiyonel | Entegrasyon notu / açıklaması (opsiyonel). |
Olası Hata Kodları
| HTTP | Hata Kodu | Açıklama & Çözüm |
|---|---|---|
| 422 | INVALID_WEBHOOK_URL | URL HTTPS protokolünde değil veya özel ağ adresini işaret ediyor. |
/v1/webhooks/v1/webhooks/{webhook_id}Webhook Aboneliğini Sil
Belirtilen webhook aboneliğini kalıcı olarak siler ve bekleyen yeniden deneme teslimatlarını durdurur.
İstek Parametreleri
| Alan | Konum | Tip | Zorunluluk | Açıklama |
|---|---|---|---|---|
| webhook_id | Path | string | Zorunlu | Silinecek webhook kimliği (örn. whk_01JCPD4E6F8G0H2J4K6M). |
/v1/webhooks/{webhook_id}
