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.
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. POSTisteği alır, JSON gövde okur.- 5 saniye içinde
2xxdö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 3000Aldığı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:
| Alan | Ne yazılır |
|---|---|
| URL | https://sunucunuz.com/hikie/webhook |
| İsim | Kendinizin ayırt etmesi için, örn. "Store prod" |
| Eventler | Dinlemek istedikleriniz — başlangıç için order.paid |
Kaydettiğiniz anda size bir secret gösterilir:
whsec_8f3c1a92be04d5e7a61b0c94f2d738ae5019cb37e64a2d8f1057be93c4a20d6fBu 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:
HIKIE_WEBHOOK_SECRET=whsec_8f3c1a92be04d5e7a61b0c94f2d738ae5019cb37e64a2d8f1057be93c4a20d6fTest 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:
- Zaman damgası kabul penceresinde mi (tekrar oynatma koruması)
- İmza eşleşiyor mu — sabit zamanlı karşılaştırma
Hikie-Webhook-Iddaha önce işlendi mi (tekrar koruması)
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);Gerçek eventlere geçin
Test geçtiyse abonelikte dinlediğiniz eventleri genişletin. En sık başlanan yer
order.paid:
{
"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.