Olay Bildirimleriwebhooks:manageX-Armonika-SignatureHMAC-SHA256

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.createdHerhangi bir bağlı satış kanalından yeni bir sipariş düştüğünde tetiklenir.
order.status_updatedSiparişin durumu (hazırlanıyor, kargoda, teslim edildi, iade) değiştiğinde tetiklenir.
order.cancelledSipariş 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.updatedBir varyantın kullanılabilir stok miktarı değiştiğinde tetiklenir.
discrepancy.detectedAna stok/fiyat kaynağı ile pazaryeri ilanı arasında fark oluştuğunda tetiklenir.
Örnek Webhook Teslimat Gövdesi
POST /webhooks/armonika HTTP/1.1
Content-Type: application/json
X-Armonika-Event: order.created
X-Armonika-Delivery-Id: dlv_01JCPE2K4M6N8P0Q2R4S
X-Armonika-Timestamp: 1763372500
X-Armonika-Signature: sha256=8f4e2c1a9b0d7e6f5a4c3b2d1e0f9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f
 
{
"id": "evt_01JCPE2K4M6N8P0Q2R4S",
"event": "order.created",
"created_at": "2026-11-17T09:41:40Z",
"data": {
"id": "ord_01JCP7Y8N2K4M6R8T0V2",
"channel": "trendyol",
"order_number": "1029384756",
"status": "processing",
"total_amount": 1350.0,
"currency": "TRY"
}
}

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. 1. İmzalanan Metni Oluşturun: X-Armonika-Timestamp başlığı ile ayrıştırılmamış ham istek gövdesini (rawBody) nokta (.) ile birleştirin: ${timestamp}.${rawBody}.
  2. 2. HMAC-SHA256 Hesaplayın: Mağaza Secret Key değerinizle hex özetini üretin ve sha256=<hex> biçiminde sabit süreli (timingSafeEqual) karşılaştırın.
Ham Gövde (Raw Body) ve Tekrar Saldırısı Koruması
JSON.parse yapıp tekrar JSON.stringify uygulamak boşluk/anahtar sırasını değiştirebileceği için imzayı bozar; her zaman ham UTF-8 gövdeyi kullanın ve 5 dakikadan eski X-Armonika-Timestamp değerlerini reddedin.
Node.js / TypeScript — HMAC Doğrulama
import crypto from "node:crypto";
 
export function verifyArmonikaWebhook(
rawBody: string,
signatureHeader: string | undefined,
timestampHeader: string | undefined,
secretKey: string
): boolean {
if (!signatureHeader || !timestampHeader) return false;
 
// 5 dakika (300 sn) tekrar saldırısı (replay) toleransı
const nowSec = Math.floor(Date.now() / 1000);
if (Math.abs(nowSec - Number(timestampHeader)) > 300) {
return false;
}
 
const expected =
"sha256=" +
crypto
.createHmac("sha256", secretKey)
.update(`${timestampHeader}.${rawBody}`, "utf8")
.digest("hex");
 
const givenBuf = Buffer.from(signatureHeader, "utf8");
const expectedBuf = Buffer.from(expected, "utf8");
 
return (
givenBuf.length === expectedBuf.length &&
crypto.timingSafeEqual(givenBuf, expectedBuf)
);
}
GET/v1/webhooks

Kayıtlı Webhook Uçlarını Listele

Basic base64(apiKey:secretKey)Kapsam: webhooks:manageLimit: 60 istek / dk

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.

GET/v1/webhooks
curl -X GET "https://api.armonika.app/v1/webhooks" \
-u "arm_9f8a7b6c5d4e:arm_sec_1a2b3c4d5e6f7g8h9i0j"
Yanıt (Response)
HTTP/1.1 200 OK
{
"success": true,
"data": [
{
"id": "whk_01JCPD4E6F8G0H2J4K6M",
"url": "https://erp.ornekmarka.com/webhooks/armonika",
"events": [
"order.created",
"order.status_updated",
"inventory.updated"
],
"is_active": true,
"created_at": "2026-10-20T11:00:00Z"
}
]
}
POST/v1/webhooks

Yeni Webhook Aboneliği Oluştur

Basic base64(apiKey:secretKey)Kapsam: webhooks:manageLimit: 30 istek / dk

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

AlanKonumTipZorunlulukAçıklama
urlBody (JSON)string (https url)ZorunluBildirimlerin POST edileceği genel erişime açık HTTPS uç nokta adresi.
eventsBody (JSON)string[]ZorunluAbone olunacak olaylar: order.created, order.status_updated, order.cancelled, product.updated, inventory.updated, discrepancy.detected.
descriptionBody (JSON)stringOpsiyonelEntegrasyon notu / açıklaması (opsiyonel).

Olası Hata Kodları

HTTPHata KoduAçıklama & Çözüm
422INVALID_WEBHOOK_URLURL HTTPS protokolünde değil veya özel ağ adresini işaret ediyor.
POST/v1/webhooks
curl -X POST "https://api.armonika.app/v1/webhooks" \
-u "arm_9f8a7b6c5d4e:arm_sec_1a2b3c4d5e6f7g8h9i0j" \
-H "Content-Type: application/json" \
-d '{
"url": "https://erp.ornekmarka.com/webhooks/armonika",
"events": ["order.created", "order.status_updated", "order.cancelled"],
"description": "Canlı ERP Sipariş Dinleyicisi"
}'
Yanıt (Response)
HTTP/1.1 201 Created
{
"success": true,
"data": {
"id": "whk_01JCPD4E6F8G0H2J4K6M",
"url": "https://erp.ornekmarka.com/webhooks/armonika",
"events": ["order.created", "order.status_updated", "order.cancelled"],
"is_active": true,
"created_at": "2026-11-17T09:40:00Z"
}
}
DELETE/v1/webhooks/{webhook_id}

Webhook Aboneliğini Sil

Basic base64(apiKey:secretKey)Kapsam: webhooks:manageLimit: 30 istek / dk

Belirtilen webhook aboneliğini kalıcı olarak siler ve bekleyen yeniden deneme teslimatlarını durdurur.

İstek Parametreleri

AlanKonumTipZorunlulukAçıklama
webhook_idPathstringZorunluSilinecek webhook kimliği (örn. whk_01JCPD4E6F8G0H2J4K6M).
DEL/v1/webhooks/{webhook_id}
curl -X DELETE "https://api.armonika.app/v1/webhooks/whk_01JCPD4E6F8G0H2J4K6M" \
-u "arm_9f8a7b6c5d4e:arm_sec_1a2b3c4d5e6f7g8h9i0j"
Yanıt (Response)
HTTP/1.1 200 OK
{
"success": true,
"data": {
"id": "whk_01JCPD4E6F8G0H2J4K6M",
"deleted": true
}
}