hikiehikieDeveloper Documentation

Hızlı başlangıç

Abonelik oluşturmaktan ilk doğrulanmış teslimata kadar adım adım.

Bu sayfanın sonunda çalışan bir webhook endpoint'iniz olacak: imzayı doğrulayan, tekrarları yutan ve hikie'ye 200 dönen bir endpoint.

Endpoint'i açın

Önce her isteğe 200 dönen bir iskelet kurun. İmzayı birazdan ekleyeceğiz.

server.js
import express from 'express';

const app = express();

// Ham gövdeyi saklıyoruz — imza doğrulaması buna ihtiyaç duyacak.
app.use('/hikie/webhook', express.raw({ type: 'application/json' }));

app.post('/hikie/webhook', (req, res) => {
  console.log(req.headers['hikie-event'], req.body.toString('utf8'));
  res.sendStatus(200);
});

app.listen(3000);

Üç şart:

  • HTTPS — http:// adresler kabul edilmez.
  • POST isteği alır, JSON gövde okur.
  • 5 saniye içinde 2xx döner.

Ham gövdeye erişebilmeniz gerekiyor. Çoğu framework JSON'u otomatik parse edip ham metni atar; imza ham baytlar üzerinden hesaplandığı için parse edilmiş nesneyi yeniden serileştirmek imzayı bozar.

Yerelde geliştiriyorsanız tünel açın

hikie yalnızca herkese açık HTTPS adreslerine istek atar; localhost hedef olamaz. Geliştirme sırasında bir tünel kullanın:

npx localtunnel --port 3000

Aldığınız https://… adresi bir sonraki adımda kullanacağınız URL'dir. Alternatifler ve ayrıntı: Test etme.

Aboneliği oluşturun

hikie panelinde Webhooklar sekmesine gidip yeni abonelik ekleyin:

AlanNe yazılır
URLhttps://sunucunuz.com/hikie/webhook
İsimKendinizin ayırt etmesi için, örn. "Store prod"
EventlerDinlemek istedikleriniz — başlangıç için order.paid

Kaydettiğiniz anda size bir secret gösterilir:

whsec_8f3c1a92be04d5e7a61b0c94f2d738ae5019cb37e64a2d8f1057be93c4a20d6f

Bu secret yalnızca bir kez gösterilir. hikie onu şifreli saklar ve bir daha düz metin olarak göstermez. Kaybederseniz tek yol yeni bir secret üretmek ("Secret'ı yenile") — bu da eskisini anında geçersiz kılar.

Secret'ı sunucunuzda bir ortam değişkeninde tutun; kod deposuna koymayın:

.env
HIKIE_WEBHOOK_SECRET=whsec_8f3c1a92be04d5e7a61b0c94f2d738ae5019cb37e64a2d8f1057be93c4a20d6f

Test gönderin

Abonelik satırındaki Test gönder düğmesi endpoint'inize bir test.ping yollar. Gerçek bir sipariş beklemeden tüm zinciri denemenin yolu budur.

Endpoint'inize şuna benzer bir istek düşmeli:

POST /hikie/webhook HTTP/1.1
Content-Type: application/json
Hikie-Event: test.ping
Hikie-Webhook-Id: wh_1f0c8ab29e7d453b6c1a0e94f27d3b85
Hikie-Account-Id: 6512ab3d9f1e4c0012a7bc45
Hikie-Timestamp: 1785945600
Hikie-Occurred-At: 2026-08-07T09:20:00.000Z
Hikie-Api-Version: 2026-09-04
Hikie-Signature: 4c1f9d0a7e2b8c6f1d3a5e90b47c2f8ae61d0937c5b2408fe93a17d6c2b0459e
Hikie-Delivery-Attempt: 1

{"subscriptionId":"66b2c1a70f5e8d4319ab72c6","message":"Hikie webhook bağlantınız çalışıyor.","dateSent":"2026-08-07T09:20:00.000Z"}

Gelmediyse Hata ayıklama sayfasına bakın. Panelde Teslimat geçmişi, isteğin gerçekten gönderilip gönderilmediğini ve sunucunuzun ne döndüğünü gösterir.

İmzayı doğrulayın

İmzayı doğrulamayan bir endpoint, adresini bilen herkesin sipariş uydurabileceği bir endpoint'tir. Üç kontrol:

  1. Zaman damgası kabul penceresinde mi (tekrar oynatma koruması)
  2. İmza eşleşiyor mu — sabit zamanlı karşılaştırma
  3. Hikie-Webhook-Id daha önce işlendi mi (tekrar koruması)
server.js
import crypto from 'node:crypto';
import express from 'express';

const app = express();
const SECRET = process.env.HIKIE_WEBHOOK_SECRET;
const TOLERANCE_SECONDS = 300;

app.use('/hikie/webhook', express.raw({ type: 'application/json' }));

app.post('/hikie/webhook', async (req, res) => {
  const timestamp = req.get('Hikie-Timestamp');
  const signature = req.get('Hikie-Signature');
  const webhookId = req.get('Hikie-Webhook-Id');
  const rawBody = req.body.toString('utf8');

  // 1) Zaman damgası penceresi
  const age = Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp));
  if (!Number.isFinite(age) || age > TOLERANCE_SECONDS) {
    return res.sendStatus(400);
  }

  // 2) İmza — sabit zamanlı karşılaştırma
  const expected = crypto
    .createHmac('sha256', SECRET)
    .update(`${timestamp}.${rawBody}`, 'utf8')
    .digest('hex');

  const a = Buffer.from(expected, 'utf8');
  const b = Buffer.from(signature ?? '', 'utf8');
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    return res.sendStatus(401);
  }

  // 3) Tekrar koruması — aynı webhookId ikinci kez gelirse işleme
  if (await alreadyProcessed(webhookId)) return res.sendStatus(200);
  await markProcessed(webhookId);

  // 4) Ağır işi arka plana at, hemen yanıt dön
  const payload = JSON.parse(rawBody);
  await enqueue({ eventType: req.get('Hikie-Event'), webhookId, payload });

  res.sendStatus(200);
});

app.listen(3000);

Tam ve üretime hazır sürümler: Express · Fastify · NestJS

Gerçek eventlere geçin

Test geçtiyse abonelikte dinlediğiniz eventleri genişletin. En sık başlanan yer order.paid:

order.paid gövdesi
{
  "orderId": "17716204135268844HKS",
  "status": "COMPLETED",
  "storeSlug": "magazam",
  "dateCreated": "2026-08-07T09:18:11.000Z",
  "currency": "TRY",
  "totals": {
    "subtotal": "249.90",
    "shipping": "0.00",
    "discount": "0.00",
    "total": "249.90"
  },
  "discounts": [],
  "customerInfo": {
    "firstName": "Ayşe",
    "lastName": "Yılmaz",
    "email": "[email protected]",
    "phone": "+905321234567",
    "address": "Bağdat Cad. No 12 D:4",
    "district": "Kadıköy",
    "city": "İstanbul",
    "state": null,
    "postcode": "34710",
    "country": "TR"
  },
  "billingInfo": null,
  "items": [
    {
      "itemId": "66b1efd21c9a4e0021f3ab77",
      "title": "VIP Paket",
      "type": "DIGITAL",
      "variant": { "sku": null, "name": "30 gün" },
      "quantity": 1,
      "unitPrice": "249.90",
      "total": "249.90",
      "isUpsell": false,
      "stockQuantity": 99
    }
  ],
  "isLink": false,
  "linkId": null,
  "merchantOrderId": null,
  "attribution": null,
  "cargo": null
}

Tüm eventler ve alanları: Event kataloğu.

Yayına almadan önce

Bu sayfada