Lisans eventleri
license.created, license.revoked ve license.restored — Yazılım modülündeki lisans anahtarlarını kendi sisteminize aktarın.
| Event | Ne zaman tetiklenir |
|---|---|
license.created | Bir üye için lisans anahtarı üretildi |
license.revoked | Satı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çim | whsec_… | hks_… (mağaza API anahtarı) — hsw_… (eski, çalışmaya devam eder) |
| Yön | hikie → sizin sunucunuz | sizin sunucunuz → hikie |
| Ne yapar | Gelen isteğin gerçekten hikie'den geldiğini doğrularsınız | Giden istekte kimliğinizi kanıtlarsınız |
| Nasıl kullanılır | Hikie-Signature başlığını HMAC-SHA256 ile karşılaştırırsınız | Authorization: Bearer hks_… başlığı |
| Nereden alınır | Panel → Webhooklar → abonelik oluştururken | Panel → 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.
{
"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"
}
}{
"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ışı
| Event | Tekrar |
|---|---|
license.created | Lisans başına bir kez |
license.revoked | Her iptalde bir kez |
license.restored | Her 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.