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 gereken | Yapmamanız gereken |
|---|---|
Boş bir 200 dönün | 64 KB'tan büyük gövde döndürmek |
| Doğrulamadan sonra hemen dönün | Yanıttan önce ağır iş yapmak |
Geçici sorunda 503 dönün | Geçici sorunda 401/403 dönmek — kalıcı sayılır |
Bozuk imzada 400 dönün | Sessizce 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ı:
| Framework | Yöntem |
|---|---|
| Express | express.raw({ type: 'application/json' }) |
| Fastify | addContentTypeParser ile ham buffer saklamak |
| NestJS | NestFactory.create(AppModule, { rawBody: true }) |
| Next.js (App Router) | await request.text() |
| Koa | koa-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:
wwwyö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.