hikiehikieDeveloper Documentation
Entegrasyon

Endpoint gereksinimleri

Webhook endpoint'inizin karşılaması gereken şartlar ve kaçınılması gereken tuzaklar.

Zorunlu

HTTPS

Geçerli bir sertifikayla. http:// adresler kabul edilmez.

POST kabul eder

Content-Type: application/json gövde okur.

5 saniyede yanıt

Herhangi bir 2xx. Gövde okunmaz.

Ham gövdeye erişim

İmza ham baytlar üzerinden hesaplanır.

Yanıt kuralları

Yapmanız gerekenYapmamanız gereken
Boş bir 200 dönün64 KB'tan büyük gövde döndürmek
Doğrulamadan sonra hemen dönünYanıttan önce ağır iş yapmak
Geçici sorunda 503 dönünGeçici sorunda 401/403 dönmek — kalıcı sayılır
Bozuk imzada 400 dönünSessizce 200 dönüp isteği yutmak

401 ve 403 kalıcı hata sayılır: iki ardışık teslimatta aboneliğiniz failing durumuna düşer. İmza doğrulaması geçici bir sebeple (örn. secret henüz yüklenmemiş) başarısızsa 503 dönün ki yeniden denensin.

Yanıt süresi

5 saniye, ağ gecikmesi dâhil toplam süredir. Şu işleri yanıttan sonra yapın:

sequenceDiagram
participant H as hikie
participant S as Sunucunuz
participant Q as Kuyruğunuz
participant W as Worker

H->>S: POST /hikie/webhook
S->>S: imza doğrula (~1 ms)
S->>Q: işi yaz (~5 ms)
S-->>H: 200 OK
Note over H,S: toplam ~10 ms
Q->>W: iş alınır
W->>W: dış sisteme istek,<br/>DB yazma, e-posta…

Kuyruk altyapınız yoksa en basit hâli bile yeterli:

res.sendStatus(200);
// yanıt gönderildikten sonra çalışır
setImmediate(() => handleEvent(eventType, payload).catch(console.error));

Bu basit yaklaşımın riski: süreç yanıt ile işleme arasında çökerse event kaybolur. Gerçek bir kuyruk (BullMQ, RabbitMQ, hatta bir veritabanı tablosu) bu riski ortadan kaldırır.

Ham gövde neden önemli

İmza şu dizenin HMAC'idir:

"<Hikie-Timestamp>" + "." + "<gövdenin ham baytları>"

Framework'ünüz JSON'u parse edip ham metni atarsa, imzayı doğrulamak için gövdeyi yeniden üretmeniz gerekir — ve yeniden üretilen JSON asla orijinaliyle bayt bayt aynı olmaz:

// Gelen ham gövde:
'{"orderId":"17716204135268844HKS","totals":{"total":"249.90"}}'

// JSON.parse → JSON.stringify sonrası:
'{"orderId":"17716204135268844HKS","totals":{"total":"249.90"}}'
// …bu örnekte aynı görünebilir, ama alan sırası, ondalık gösterim,
// Unicode kaçışları ve boşluklar garanti değildir. İmza tutmaz.

Framework'e göre ham gövdeyi alma yolları:

FrameworkYöntem
Expressexpress.raw({ type: 'application/json' })
FastifyaddContentTypeParser ile ham buffer saklamak
NestJSNestFactory.create(AppModule, { rawBody: true })
Next.js (App Router)await request.text()
Koakoa-bodyparser yerine raw-body

Birden fazla event tipi

Tek bir endpoint tüm eventleri karşılayabilir; tipi Hikie-Event başlığından okursunuz:

switch (eventType) {
  case 'order.paid':
    return grantPurchase(payload);
  case 'order.updated':
    return handleOrderStatus(payload);
  case 'order.shipmentUpdated':
    return handleShipmentUpdate(payload);
  case 'test.ping':
    return; // bilgi amaçlı, iş yok
  default:
    // Bilmediğiniz bir tip gelirse yine 200 dönün — yeni event tipleri
    // eklenebilir ve bunlar aboneliğinizi failing'e itmemeli.
    return;
}

Tanımadığınız event tiplerinde hata dönmeyin. Katalog zamanla genişleyebilir; bilinmeyen bir tipe 400 dönmek aboneliğinizi gereksiz yere failing yapar.

Yönlendirme yapmayın

3xx yanıtları takip edilmez ve kalıcı hata sayılır. Sık karşılaşılan sebepler:

  • www yönlendirmesi — abonelikte nihai adresi yazın
  • Sondaki eğik çizgi yönlendirmesi (/hook → /hook/) — hangisi doğruysa onu yazın
  • HTTP → HTTPS yönlendirmesi — zaten HTTPS yazmanız gerekiyor

Güvenlik duvarı ve WAF

hikie sabit bir IP aralığından gelmez; IP'ye göre izin listesi oluşturmayın. WAF kullanıyorsanız webhook yolunu istisna tutmanız gerekebilir — JSON gövdeli POST istekleri bazı kural setlerinde engelleniyor ve bu 403 olarak, yani kalıcı hata olarak görünüyor.

User-Agent başlığı Hikie-Webhooks/2.0 olarak gelir; kural yazacaksanız buna göre yazabilirsiniz — ama bunu kimlik doğrulaması yerine kullanmayın, taklit edilebilir.

Bu sayfada