hikiehikieDeveloper Documentation
Eventler

Lisans eventleri

license.created, license.revoked ve license.restored — Yazılım modülündeki lisans anahtarlarını kendi sisteminize aktarın.

EventNe zaman tetiklenir
license.createdBir üye için lisans anahtarı üretildi
license.revokedSatıcı bir anahtarı iptal etti
license.restoredİptal edilmiş bir anahtar yeniden geçerli kılındı

Bu eventler yalnızca Yazılım modülü kurulu mağazalarda üretilir. Modülü kurmamış bir mağazada abone olabilirsiniz, hiç teslimat almazsınız.

Bu eventler lisansın geçerliliğini bildirmez, yalnızca kaydın değiştiğini bildirir. Bir müşteri iade aldığında ya da aboneliği bittiğinde hiçbir event gitmez — çünkü lisans o anda "iptal edildi" diye işaretlenmiyor; geçerlilik her doğrulama isteğinde canlı hesaplanıyor.

Yazılımınızın "bu müşteri hâlâ ödüyor mu" sorusunun tek doğru cevabı POST /v1/licenses/validate'tir. Webhook'u yazılımınızın kilidini açmak için DEĞİL, kendi veritabanınızı senkron tutmak için kullanın.

İki ayrı anahtar — karıştırmayın

Yazılım modülüyle çalışırken iki farklı secret'a ihtiyacınız var ve bunlar ters yönlerde çalışır. Aynı anahtarın iki kullanımı değildir; iki ayrı anahtardır ve birbirinin yerine geçmezler.

Webhook imza secret'ıLisans doğrulama anahtarı
Biçimwhsec_…hks_… (mağaza API anahtarı) — hsw_… (eski, çalışmaya devam eder)
Yönhikie → sizin sunucunuzsizin sunucunuz → hikie
Ne yaparGelen isteğin gerçekten hikie'den geldiğini doğrularsınızGiden istekte kimliğinizi kanıtlarsınız
Nasıl kullanılırHikie-Signature başlığını HMAC-SHA256 ile karşılaştırırsınızAuthorization: Bearer hks_… başlığı
Nereden alınırPanel → Webhooklar → abonelik oluştururkenPanel → Ayarlar → API Anahtarları (eski hsw_…: Yazılım modülü → Geliştirici sekmesi)

whsec_… ile POST /v1/licenses/validate çağırırsanız 401 alırsınız — doğrulama ucu webhook secret'ını tanımaz. Bu, entegrasyonda en sık yapılan hatadır.

Doğrulama anahtarını nereden alırım

Mağaza API anahtarınızı kullanın: panel → Ayarlar → API Anahtarları → Anahtar oluştur. hks_ ile başlar, bir kez gösterilir ve İndirimler bölümünde kullandığınız anahtarın aynısıdır — sunucunuzun hikie'ye gönderdiği her istek için tek anahtar.

Yazılım modülünün Geliştirici sekmesinden alınan eski hsw_… anahtarlar çalışmaya devam eder; sahadaki yazılımınızı değiştirmeniz gerekmez.

Her iki anahtar da yalnızca üretildiği anda bir kez gösterilir; veritabanında yalnızca hash'i durur, biz bile ham hâlini okuyamayız. Kaybederseniz tek çare yenilemektir — ve yenileme eskisini anında geçersiz kılar (mağaza API anahtarıyla lisans doğrulamada bu en fazla bir dakika sürebilir). Canlıda çalışan bir yazılımınız varsa, yeni anahtarı dağıtana kadar yenilemeyin.

Mağaza API anahtarı mağazadaki tüm Yazılım modüllerini kapsar: lisans kendi anahtarıyla bulunur. Eski hsw_… anahtar ise modül başınadır ve yalnızca o modülün lisanslarını doğrular.

license.created ne zaman gider — satın alma anında DEĞİL

Anahtar satın alma olayıyla değil talep anında üretilir: üye Yazılım modülünü ilk açtığında. Yani license.created, müşteri ödemeyi yaptıktan saatler, bazen günler sonra gelebilir.

Bu bilinçli bir tercih: anahtar, erişimin türevi olduğu için kaçan bir ödeme bildirimi "anahtarım gelmedi" vakası üretemiyor. Bedeli, satın alma anını bu eventten öğrenememeniz — onun için order.paid var.

Aynı müşteri modülü kaç kez açarsa açsın license.created bir kez gider. Anahtar zaten varsa yeni bir event üretilmez.

Payload

Üç eventin gövdesi aynı yapıdadır.

license.created
{
  "licenseId": "66c3a81d5f2b4e0021aa9931",
  "key": "K4RT-9MXQ-2BVF-7HJD",
  "status": "active",
  "usesCount": 0,
  "metadata": null,
  "metadataBoundAt": null,
  "revokedAt": null,
  "createdAt": "2026-09-20T09:00:00.000Z",
  "lastValidatedAt": null,
  "module": {
    "appId": "66b1efd21c9a4e0021f3ab55",
    "spaceSubdomain": "magazam"
  },
  "customer": {
    "userId": "66a0c1b45f2b4e0021aa7700",
    "email": "[email protected]",
    "name": "Deniz Kaya",
    "userName": "denizk"
  }
}
license.revoked
{
  "licenseId": "66c3a81d5f2b4e0021aa9931",
  "key": "K4RT-9MXQ-2BVF-7HJD",
  "status": "revoked",
  "usesCount": 41,
  "metadata": { "hwid": "8F2A-11C9-D3E7" },
  "metadataBoundAt": "2026-09-20T09:14:02.000Z",
  "revokedAt": "2026-09-21T12:00:00.000Z",
  "createdAt": "2026-09-20T09:00:00.000Z",
  "lastValidatedAt": "2026-09-21T08:31:55.000Z",
  "module": {
    "appId": "66b1efd21c9a4e0021f3ab55",
    "spaceSubdomain": "magazam"
  },
  "customer": {
    "userId": "66a0c1b45f2b4e0021aa7700",
    "email": "[email protected]",
    "name": "Deniz Kaya",
    "userName": "denizk"
  }
}

Alan

Tip

status yalnızca satıcının elle yaptığı iptal durumunu taşır. İadesi yapılmış ya da aboneliği bitmiş bir müşterinin anahtarı bu alanda hâlâ "active" görünür — buna rağmen POST /v1/licenses/validate onu geçersiz sayar. İki kaynak çeliştiğinde doğru olan doğrulama ucudur.

customer.email ve customer.name boş gelebilir. Kullanıcı servisi o anda yanıt vermediyse event yine gönderilir, bu alanlar null olur. Müşteriyi kendi tarafınızda eşleştirirken her zaman customer.userId'ye dayanın — o alan asla boş gelmez.

Doğru kullanım deseni

Webhook'u aynaya, doğrulama ucunu kilide bağlayın:

// 1) Webhook: kendi veritabanınızı güncel tutar. Yetki kararı VERMEZ.
async function onLicenseEvent(eventType, data) {
  await db.upsertLicense({
    id: data.licenseId,
    key: data.key,
    customerId: data.customer.userId,
    email: data.customer.email,
    revokedAt: data.revokedAt,
  });

  if (eventType === 'license.created') {
    await crm.tagCustomer(data.customer.email, 'yazilim-musterisi');
  }
}

// 2) Yazılımınız: kilidi her açılışta buradan sorar.
//    DOGRULAMA_ANAHTARI = `hks_…` mağaza API anahtarınız (Ayarlar → API Anahtarları).
//    Webhook imza secret'ı (`whsec_…`) BURADA İŞE YARAMAZ — 401 döner.
async function programAcilisi(girilenAnahtar, cihazId) {
  const cevap = await fetch('https://hikie-software-production.up.railway.app/v1/licenses/validate', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${DOGRULAMA_ANAHTARI}`,
    },
    body: JSON.stringify({ key: girilenAnahtar, metadata: { hwid: cihazId } }),
  });

  const { valid, reason } = await cevap.json();
  return valid; // iade/iptal burada yakalanır, webhook'ta değil
}

Yalnızca license.revoked dinleyip yazılımınızın kilidini ona bağlarsanız, iade alan bir müşteri yazılımınızı süresiz kullanmaya devam eder — çünkü iade bu eventi üretmez.

İade ve abonelik bitişini nasıl öğrenirim

İki yolu var:

Tekrar davranışı

EventTekrar
license.createdLisans başına bir kez
license.revokedHer iptalde bir kez
license.restoredHer geri almada bir kez

Satıcı aynı anahtarı iptal edip geri alıp yine iptal edebilir; bunların her biri ayrı bir eventtir ve ayrı bir Hikie-Webhook-Id taşır. Sıralamayı Hikie-Occurred-At başlığından yapın — teslimat sırası garanti değildir.

async function onLicenseEvent(eventType, data, occurredAt) {
  const mevcut = await db.getLicense(data.licenseId);

  // Geciken eski bir event yeniyi ezmesin.
  if (mevcut && mevcut.updatedAt >= occurredAt) return;

  await db.upsertLicense({ ...data, updatedAt: occurredAt });
}

Teslimat garantisi

Lisans eventleri kalıcı bir kuyruğa yazılır ve hikie-webhook'un yeniden deneme zinciriyle gönderilir. Yine de bir eventin hiç üretilememesi mümkündür (örneğin modül kaydı çözülemediğinde). Kritik bir iş akışını — müşterinin yazılımı açabilmesi gibi — tek bir eventin varlığına bağlamayın; doğrulama ucu her zaman elinizdedir ve durumu kendisi hesaplar.

Bu sayfada